TypeScript Dependency Injection: TSyringe vs InversifyJS vs TypeDI — IoC Containers for Node.js

Dependency Injection (DI) and Inversion of Control (IoC) are foundational patterns for building maintainable, testable TypeScript applications. Three libraries lead the TypeScript DI ecosystem: TSyringe (Microsoft’s lightweight DI container with decorator support), InversifyJS (a feature-rich IoC container with advanced binding capabilities), and TypeDI (a decorator-driven container emphasizing simplicity). Each approaches dependency management with a different philosophy, from minimal configuration to enterprise-grade flexibility.

Comparison Table

Getting Started: Installation and Basic Setup

TSyringe

TSyringe is Microsoft’s lightweight, reflection-based DI container. It leverages TypeScript’s reflect-metadata for automatic dependency resolution:

1

npm install tsyringe reflect-metadata

1
2
3
4
5
6
7

// Configure tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

import "reflect-metadata";
import { container, injectable, inject, singleton } from "tsyringe";

// Define your services
@injectable()
class Database {
  connect() { console.log("DB connected"); }
  query(sql: string) { return [{ id: 1, name: "Alice" }]; }
}

@injectable()
class Logger {
  log(message: string) { console.log(`[LOG] ${message}`); }
}

@singleton()
class UserService {
  constructor(
    private db: Database,
    private logger: Logger
  ) {}

  getUsers() {
    this.logger.log("Fetching users...");
    return this.db.query("SELECT * FROM users");
  }
}

// Resolve — TSyringe auto-wires constructor dependencies
const userService = container.resolve(UserService);
userService.getUsers();

InversifyJS

InversifyJS is the most feature-rich TypeScript DI container, offering named bindings, tagged bindings, middleware, and a module system:

1

npm install inversify reflect-metadata

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

import "reflect-metadata";
import { Container, injectable, inject, named, tagged } from "inversify";

// Define symbols for interface-based binding
const TYPES = {
  Database: Symbol.for("Database"),
  Logger: Symbol.for("Logger"),
  UserService: Symbol.for("UserService"),
};

// Interfaces enable true IoC
interface IDatabase {
  connect(): void;
  query(sql: string): any[];
}

interface ILogger {
  log(message: string): void;
}

@injectable()
class PostgresDatabase implements IDatabase {
  connect() { console.log("Postgres connected"); }
  query(sql: string) { return [{ id: 1, name: "Alice" }]; }
}

@injectable()
class ConsoleLogger implements ILogger {
  log(message: string) { console.log(`[LOG] ${message}`); }
}

@injectable()
class UserService {
  constructor(
    @inject(TYPES.Database) private db: IDatabase,
    @inject(TYPES.Logger) private logger: ILogger
  ) {}

  getUsers() {
    this.logger.log("Fetching users...");
    return this.db.query("SELECT * FROM users");
  }
}

// Bind interfaces to implementations
const container = new Container();
container.bind<IDatabase>(TYPES.Database).to(PostgresDatabase);
container.bind<ILogger>(TYPES.Logger).to(ConsoleLogger);
container.bind<UserService>(TYPES.UserService).to(UserService);

const userService = container.get<UserService>(TYPES.UserService);
userService.getUsers();

TypeDI

TypeDI emphasizes developer experience with minimal configuration and sensible defaults:

1

npm install typedi reflect-metadata

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

import "reflect-metadata";
import { Container, Service, Inject } from "typedi";

@Service()
class Database {
  connect() { console.log("DB connected"); }
  query(sql: string) { return [{ id: 1, name: "Alice" }]; }
}

@Service()
class Logger {
  log(message: string) { console.log(`[LOG] ${message}`); }
}

@Service()
class UserService {
  // TypeDI can auto-wire by type
  constructor(private db: Database, private logger: Logger) {}

  getUsers() {
    this.logger.log("Fetching users...");
    return this.db.query("SELECT * FROM users");
  }
}

// No need to manually register — TypeDI discovers @Service() classes
const userService = Container.get(UserService);
userService.getUsers();

// Named services for multiple implementations
@Service({ id: "postgres" })
class PostgresDB { connect() { return "Postgres"; } }

@Service({ id: "mysql" })
class MySQLDB { connect() { return "MySQL"; } }

const pg = Container.get<PostgresDB>("postgres");

Advanced Patterns: Testing with DI Containers

DI containers shine in testing — you can swap real implementations for mocks without changing production code. Here’s how each library handles test doubles:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// TSyringe: Register mock before test
container.register(Database, { useValue: mockDb });
const service = container.resolve(UserService);

// InversifyJS: Rebind for test
container.unbind(TYPES.Database);
container.bind<IDatabase>(TYPES.Database).toConstantValue(mockDb);

// TypeDI: Set explicit value
Container.set(Database, mockDb);

InversifyJS has the edge here with its explicit binding API — test setup is predictable and doesn’t rely on container state from other tests. TSyringe’s register and reset work well but require more careful test isolation. TypeDI’s Container.set is the simplest but offers the least flexibility for complex test scenarios.

Framework Integration

InversifyJS has the richest ecosystem: official packages for Express (inversify-express-utils) and an established pattern for NestJS custom providers. Its decorator-based approach maps naturally to NestJS’s module system.

TSyringe integrates well with any framework through manual resolution in route handlers. It’s popular in non-NestJS backends and serverless functions where you want DI without framework lock-in.

TypeDI is used internally by TypeORM and Routing-Controllers, giving it strong adoption in the Typestack ecosystem. If you’re already using TypeORM, TypeDI integrates seamlessly.

Lifecycle Management and Scoping Patterns

Proper lifecycle management is what separates a DI container from a glorified service locator. Each library implements lifetime scopes differently, and understanding these differences is critical for avoiding memory leaks and stale state in long-running Node.js processes:

• Singleton scope: One instance for the entire application lifetime. Ideal for stateless services like loggers, configuration objects, and database connection pools.
• Transient scope: A new instance every time it’s requested. Use for request-scoped data like unit-of-work objects or services that carry per-operation state.
• Request scope (InversifyJS only): A single instance per HTTP request, automatically disposed when the request completes. This is the most useful scope for web applications — inject a database transaction or user context that lives exactly as long as the request.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// InversifyJS request scope — perfect for per-request database transactions
container.bind<Transaction>(TYPES.Transaction)
    .to(DatabaseTransaction)
    .inRequestScope();

// TSyringe resolution scoped — tied to a child container's lifetime
container.register(DbContext, {
    useClass: DbContext
}, { lifecycle: Lifecycle.ResolutionScoped });

// TypeDI — simple singleton/transient via decorator options
@Service({ transient: true })
class RequestScopedService { }

InversifyJS has the most mature lifecycle management, especially for web applications where request-scoped dependencies are essential. TSyringe’s ResolutionScoped lifecycle (tied to child containers) provides similar functionality but requires explicit container management. TypeDI’s simpler model is sufficient for applications with fewer lifecycle requirements, particularly CLI tools and serverless functions where most dependencies are either true singletons or short-lived.

Why Self-Host Your DI Strategy?

Dependency injection isn’t just about clean code — it’s about architectural flexibility. By decoupling your services from their implementations, you can swap databases, cache backends, and logging providers without touching business logic. Combined with TypeScript’s type system, DI containers provide compile-time safety for your dependency graph, catching wiring errors before they reach production.

For related TypeScript development patterns, see our JavaScript testing frameworks comparison and our guide to JavaScript email libraries for Node.js.

FAQ

Do I need a DI container in TypeScript, or can I just use manual DI?

Manual DI works fine for small projects (5-10 services), but as your application grows, manual wiring becomes a maintenance burden. DI containers automate constructor resolution, manage lifecycles (singleton vs transient), and provide a centralized place to configure bindings. If your project has 20+ injectable classes, a container saves significant boilerplate.

What is the difference between @injectable() and @Service()?

TSyringe and InversifyJS use @injectable() (from their respective packages) to mark a class as eligible for DI. TypeDI uses @Service() for the same purpose. Both rely on TypeScript’s emitDecoratorMetadata compiler option to emit type information that the container reads at runtime. Under the hood, they all use reflect-metadata to store and retrieve constructor parameter types.

Can I use these libraries in a non-TypeScript JavaScript project?

All three libraries require TypeScript decorators and reflect-metadata, which are TypeScript-only features. For plain JavaScript DI, consider awilix (2,500+ stars) which uses a function-based API without decorators. However, for new Node.js projects, the TypeScript ecosystem is the standard choice.

How do I handle circular dependencies?

All three libraries offer lazy injection patterns for circular dependencies. In TSyringe, use @inject(delay(() => Dependency)). In InversifyJS, use @inject(TYPES.Service) with the inversify-inject-decorators package for lazy injection. TypeDI handles circular dependencies automatically through lazy loading of the dependency graph — but the cleanest solution is to refactor your code to avoid circular dependencies altogether.

Which container is best for a NestJS application?

NestJS has its own built-in DI container that is similar to — but not directly compatible with — the libraries discussed here. If you’re building a NestJS application, use NestJS’s @Module() and @Injectable() decorators. For non-NestJS TypeScript backends, InversifyJS has the richest ecosystem, TSyringe is the simplest, and TypeDI pairs well with TypeORM projects.

💰 想测试你的市场判断力？我用 Polymarket 做预测市场交易——这是全球最大的预测市场平台，从大选结果到技术监管时间线，什么都可以押注。和赌博不同，这是真正的信息市场：你懂的信息越多，胜率越高。我靠预测技术相关事件的走向已经赚了不少。用我的邀请链接注册：Polymarket.com