inversify

library8.1.0jsnpmunverified

InversifyJS is a robust and lightweight Inversion of Control (IoC) container for JavaScript and TypeScript applications, currently at version 8.1.0. It facilitates Dependency Injection (DI) by using decorators and TypeScript's reflection capabilities to manage the instantiation and injection of dependencies, promoting adherence to SOLID principles, good OOP, and IoC practices. The library is actively maintained with frequent minor and patch releases across its core and ecosystem packages, addressing new features and bug fixes. Key differentiators include its strong TypeScript integration, minimal runtime overhead, and a developer-friendly API designed to enhance modularity, testability, and maintainability. InversifyJS emphasizes a explicit dependency graph, helping developers build scalable applications by reducing coupling between components. It relies heavily on `reflect-metadata` for design-time type information, which is a fundamental aspect of its operation.

web-framework testing

npm install inversify

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · INVERSIFY

inversify

web-frameworkjavascriptv8.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Container

✓ import { Container } from 'inversify';

✗ const { Container } = require('inversify');

InversifyJS v8 is an ESM-only package. While Node.js 20.19.0+ supports `require()` for ESM, direct `import` statements are the idiomatic way. For older Node.js versions (e.g., 18 or earlier), consider upgrading or using dynamic `import()`.

@injectable

✓ import { injectable } from 'inversify';

✗ import { Injectable } from 'inversify';

Decorator for marking classes as eligible for dependency injection. Always lowercase `injectable`.

@inject

✓ import { inject } from 'inversify';

✗ import { Inject } from 'inversify';

Decorator for injecting dependencies into constructor parameters or properties. Always lowercase `inject`.

TYPES

✓ import { TYPES } from './types';

While `inversify` itself doesn't export `TYPES`, it's a common pattern to define binding identifiers (Symbols, strings, or classes) in a separate file, typically named `types.ts` or `constants.ts`, and import them for use with `container.bind()`.

reflect-metadata polyfill

✓ import 'reflect-metadata';

This import must occur *once* at the very top of your application's entry file to ensure the global `Reflect` object is available before any InversifyJS decorators are processed. Failure to do so will result in runtime errors.

This quickstart demonstrates the core concepts of InversifyJS: defining interfaces, using symbols for binding identifiers, marking classes with `@injectable`, injecting dependencies with `@inject`, configuring the `Container` with `bind().to()`, and finally resolving an instance using `container.get()`. It highlights the necessary `reflect-metadata` import.

import 'reflect-metadata'; import { Container, injectable, inject } from 'inversify'; // 1. Define interfaces (abstractions) interface Warrior { fight(): string; sneak(): string; } interface Weapon { hit(): string; } interface ThrowableWeapon { throw(): string; } // 2. Define binding identifiers (symbols or classes) const TYPES = { Warrior: Symbol.for('Warrior'), Weapon: Symbol.for('Weapon'), ThrowableWeapon: Symbol.for('ThrowableWeapon'), }; // 3. Implement concrete classes and use decorators @injectable() class Katana implements Weapon { public hit(): string { return 'cut!'; } } @injectable() class Shuriken implements ThrowableWeapon { public throw(): string { return 'hit!'; } } @injectable() class Ninja implements Warrior { private _katana: Weapon; private _shuriken: ThrowableWeapon; public constructor( @inject(TYPES.Weapon) katana: Weapon, @inject(TYPES.ThrowableWeapon) shuriken: ThrowableWeapon, ) { this._katana = katana; this._shuriken = shuriken; } public fight(): string { return this._katana.hit(); } public sneak(): string { return this._shuriken.throw(); } } // 4. Create and configure a container const myContainer = new Container(); myContainer.bind<Warrior>(TYPES.Warrior).to(Ninja); myContainer.bind<Weapon>(TYPES.Weapon).to(Katana); myContainer.bind<ThrowableWeapon>(TYPES.ThrowableWeapon).to(Shuriken); // 5. Resolve dependencies const ninja = myContainer.get<Warrior>(TYPES.Warrior); console.log(ninja.fight()); // Expected output: cut! console.log(ninja.sneak()); // Expected output: hit!

Debug

Known issues

breakingInversifyJS v8 introduced a 'sync-first' naming convention. Methods like `container.load`, `unbind`, `rebind`, and `unload` are now synchronous by default. Their asynchronous counterparts are suffixed with `Async` (e.g., `container.loadAsync`). This reverses the behavior introduced in v7, where these methods were asynchronous by default.

fix

Review all container API calls. Replace `await container.load(module)` with `container.loadAsync(module)` if asynchronous behavior is needed, or simply `container.load(module)` if synchronous is desired (which is now the default). Apply similar changes for `unbind`, `rebind`, `unload`, and `unbindAll`.

affects: >=8.0.0

breakingInversifyJS v8 is an ESM-only package and no longer provides a CommonJS build. While Node.js 20.19.0 and later (or Node.js 22+) support `require()` for ESM packages, older Node.js versions (e.g., 18 or earlier, which reached EOL in April 2025) will require projects to either upgrade Node.js or switch to dynamic `import('inversify')` where acceptable.

fix

Upgrade to Node.js 20.19.0+ or 22+. If sticking with older Node.js, replace `require('inversify')` with `import('inversify')` for async loading or transition your project to native ESM.

affects: >=8.0.0

breakingThe `ServiceIdentifier<T>` type in v8 no longer accepts an arbitrary `Function` but strictly requires `Newable` or `AbstractNewable`. This primarily impacts using classes with `protected` or `private` constructors as service identifiers, where a `Symbol` identifier should now be used instead.

fix

For classes with `protected` or `private` constructors used as identifiers, switch to `Symbol.for()` or a custom symbol as the service identifier. For typical class-based identifiers, no change is needed.

affects: >=8.0.0

breakingThe `toProvider` binding method and the `Provider` type have been completely removed in InversifyJS v8. The `Factory` pattern (introduced in v7) covers all previous use cases of `Provider` with greater flexibility and a cleaner API.

fix

Migrate any `toProvider` bindings to `toFactory` bindings, utilizing the `Factory` type.

affects: >=8.0.0

gotchaInversifyJS critically depends on `reflect-metadata` for its decorator-based dependency injection. It must be installed (`npm install reflect-metadata`) and imported once at the very top of your application's entry file: `import 'reflect-metadata';`. Failure to do so will result in runtime errors like 'Reflect is not defined' or 'TypeError: Reflect.hasOwnMetadata is not a function'.

fix

Ensure `reflect-metadata` is installed and the `import 'reflect-metadata';` statement is the first line in your main application file. Also, configure `tsconfig.json` with `"experimentalDecorators": true`, `"emitDecoratorMetadata": true`, and `"target": "ES2022"` or later.

affects: >=1.0.0

breakingInversifyJS v7 deprecated implicit injection inheritance in favor of the `@injectFromBase` decorator. In v8, custom metadata and middlewares were removed entirely with no direct replacement, contributing to library simplification.

fix

For injection inheritance, use the `@injectFromBase` decorator. If you relied on custom metadata or middlewares, you may need to reconsider your approach or implement similar functionality manually.

affects: >=7.0.0

Errors

Common errors & fixes

TypeError: Reflect.hasOwnMetadata is not a function

The `reflect-metadata` polyfill was not imported or was imported too late.

fix

Add `import 'reflect-metadata';` as the very first line of your application's entry file. Ensure `reflect-metadata` is installed as a dependency. Check `tsconfig.json` for `"emitDecoratorMetadata": true` and `"experimentalDecorators": true`.

No matching bindings found for serviceIdentifier: Symbol(MyService)

A dependency was requested from the container but no `container.bind()` call exists for that `ServiceIdentifier` (e.g., `Symbol`, string, or class).

fix

Ensure `container.bind<T>(TYPES.MyService).to(MyServiceImpl);` is called before attempting to `container.get<T>(TYPES.MyService);`. Double-check the `ServiceIdentifier` used in `bind` and `get` matches exactly.

Maximum call stack size exceeded

This typically indicates a circular dependency between services where Service A depends on Service B, and Service B directly or indirectly depends back on Service A, causing an infinite loop during instantiation.

fix

Identify the circular dependency. Strategies to resolve include: refactoring to break the cycle, using an initializer method (`@postConstruct`), using `toDynamicValue` or `toFactory` for lazy loading, or introducing an intermediate interface/abstraction.

ReferenceError: Container is not defined

The `Container` class was used without being imported or without its module being properly transpiled/resolved.

fix

Add `import { Container } from 'inversify';` to the top of your file. If using CommonJS in an environment that doesn't support `require(esm)` (e.g., Node.js < 20.19.0), you might need to use dynamic imports or transpile your code to a compatible module format.

Upgrade

Version history

8.1.0latest on npm

Audit

Dependencies

reflect-metadatarequiredRequired for runtime type introspection via TypeScript decorators; must be imported once at application entry point for the global `Reflect` object to be available.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/inversify/monorepo ↗

packagehttps://www.npmjs.com/package/inversify ↗

homepagehttps://inversify.io ↗