InversifyJS IoC Container

Common errors

• TypeError: Reflect.hasOwnMetadata is not a function

  cause 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)

  cause 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

  cause 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

  cause 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.

Warnings

• breaking InversifyJS 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`.
• breaking InversifyJS 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.
• breaking The `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.
• breaking The `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.
• gotcha InversifyJS 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.
• breaking InversifyJS 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.

Install

• npm install inversify npm
• yarn add inversify yarn
• pnpm add inversify pnpm

Imports

• Container
  wrong:

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

  correct:

  import { Container } from '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
  wrong:

  import { Injectable } from 'inversify';

  correct:

  import { injectable } from 'inversify';

  Decorator for marking classes as eligible for dependency injection. Always lowercase `injectable`.
• @inject
  wrong:

  import { Inject } from 'inversify';

  correct:

  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.

Quickstart

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!