Dependency Injection Patterns

Q: When should I adopt Awilix over manual?

When you have 10+ classes to wire and repeated new chains in main.ts. Before that, manual is clearer.

Q: Does Fastify have built-in DI?

No first-class DI. Use manual, Awilix, or fastify-decorators with care.

Q: How do I test Awilix containers?

Register test doubles: container.register({ orderRepository: asValue(inMemoryRepo) }).

Q: Request-scoped dependencies in Express?

Use AsyncLocalStorage or per-request container child scope in Awilix (scopePerRequest plugin pattern).

Q: Nest REQUEST scope performance?

REQUEST-scoped providers add overhead. Default singleton; use REQUEST only for true per-request state.

Q: Can I mix manual and Awilix?

Yes during migration. New modules register in Awilix; legacy stays manual until touched.

Q: Interface injection without runtime types?

TypeScript interfaces erase at runtime. Use abstract class, token symbol, or string token in Nest.

Q: How does DI work in workers?

Build a smaller container in worker main with job-specific deps - share pool singleton.

Q: Is new in use cases ever OK?

For value objects and pure domain types yes. For repositories and HTTP clients, no - inject them.

Q: What is the composition root in serverless?

Lambda handler top-level: cold start builds container once, reuse across invocations in same instance.

Dependency injection (DI) supplies use cases with their dependencies (repositories, gateways, loggers) instead of importing singletons. In Node.js you can wire manually, use Awilix, or rely on NestJS 11 built-in DI.

Recipe

Quick-reference recipe card - copy-paste ready.

// Manual DI - composition root
const orders = new PostgresOrderRepository(pool);
const createOrder = new CreateOrder(orders);
app.post("/orders", (req, res) => createOrder.execute(req.body));

// Awilix - container
import { createContainer, asClass, asValue } from "awilix";
const container = createContainer();
container.register({
  pool: asValue(pool),
  orderRepository: asClass(PostgresOrderRepository).singleton(),
  createOrder: asClass(CreateOrder).singleton(),
});

When to reach for this:

Tests need to swap repositories without module mocks
Multiple entry points (HTTP, worker, CLI) share use cases
Constructor parameter lists grow past 4-5 dependencies
Team adopts NestJS and wants decorator-based wiring

Working Example

// application/create-order.ts
import type { OrderRepository } from "../domain/ports/order-repository";
 
export class CreateOrder {
  constructor(private readonly orders: OrderRepository) {}
 
  async execute(input: { customerId: string; sku: string; qty: number }) {
    const order = { id: crypto.randomUUID(), ...input, status: "pending" as const };
    await this.orders.save(order);
    return order;
  }
}
 
// manual composition root
import express from "express";
import { Pool } from "pg";
import { PostgresOrderRepository } from "./infrastructure/postgres-order-repository";
import { CreateOrder } from "./application/create-order";
 
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const createOrder = new CreateOrder(new PostgresOrderRepository(pool));
 
const app = express();
app.use(express.json());
app.post("/orders", async (req, res) => {
  res.status(201).json({ data: await createOrder.execute(req.body) });
});
 
// Awilix alternative - src/container.ts
import { createContainer, asClass, asValue, InjectionMode } from "awilix";
 
export function buildContainer(pool: Pool) {
  const container = createContainer({ injectionMode: InjectionMode.CLASSIC });
  container.register({
    pool: asValue(pool),
    orderRepository: asClass(PostgresOrderRepository).singleton(),
    createOrder: asClass(CreateOrder).singleton(),
  });
  return container;
}
 
// Resolve in main
// const { createOrder } = buildContainer(pool).cradle;

What this demonstrates:

CreateOrder depends on OrderRepository interface only
Manual wiring is explicit and grep-friendly
Awilix registers classes and resolves graph automatically
Both patterns keep framework code out of use cases

Deep Dive

How It Works

Injection: dependencies passed in (constructor, factory param, or container resolve)
Composition root: main.ts or container.ts - the only place that news concrete adapters
Lifetime: singleton (one DB pool) vs transient (per-request) - default singleton for repos
NestJS: @Injectable() providers, constructor injection, module imports/exports

Pattern Comparison

Pattern	Pros	Cons	Best for
Manual	Obvious, zero magic, fast tests	Verbose at scale	<15 bindings
Awilix	Auto-wiring, scoped lifetimes	Learning curve, runtime resolve	Express/Fastify midsize
Nest DI	First-class modules, testing utils	Decorator opinion, bootstrap cost	Nest-standard teams
`proxyquire`/module mocks	Quick hack	Brittle, breaks encapsulation	Avoid in production code

NestJS Sketch

@Injectable()
export class CreateOrder {
  constructor(private readonly orders: OrderRepository) {}
}
 
@Module({
  providers: [
    CreateOrder,
    { provide: "OrderRepository", useClass: PostgresOrderRepository },
  ],
  controllers: [OrdersController],
})
export class OrdersModule {}

TypeScript Notes

// Token-based injection without string magic - use symbols or interfaces
export const OrderRepositoryToken = Symbol("OrderRepository");
type OrderRepository = import("../domain/ports/order-repository").OrderRepository;

Gotchas

Service locator anti-pattern - container.resolve scattered in routes. Fix: Resolve once at boot; inject into handlers.
Global singleton module - export const db = new Pool(). Fix: Register in composition root; pass to repos.
Circular provider dependencies in Awilix - A needs B needs A. Fix: Extract shared port or event.
Over-using Nest for 5 routes - DI ceremony without team buy-in. Fix: Manual DI until Nest is org standard.
Transient pool per request - Exhausts DB connections. Fix: Singleton pool, transient repos only if needed.

Alternatives

Alternative	Use When	Don't Use When
Manual factory functions	Small Fastify services	30+ use cases with shared deps
`tsyringe`	Decorator DI without Nest	Team avoids decorators
Pure functions + deps param	Functional style	Large graphs with shared config
No DI - import singletons	Throwaway scripts	Long-lived APIs

FAQs

When should I adopt Awilix over manual?

When you have 10+ classes to wire and repeated new chains in main.ts. Before that, manual is clearer.

Does Fastify have built-in DI?

No first-class DI. Use manual, Awilix, or fastify-decorators with care.

How do I test Awilix containers?

Request-scoped dependencies in Express?

Use AsyncLocalStorage or per-request container child scope in Awilix (scopePerRequest plugin pattern).

Nest REQUEST scope performance?

REQUEST-scoped providers add overhead. Default singleton; use REQUEST only for true per-request state.

Can I mix manual and Awilix?

Yes during migration. New modules register in Awilix; legacy stays manual until touched.

Interface injection without runtime types?

TypeScript interfaces erase at runtime. Use abstract class, token symbol, or string token in Nest.

How does DI work in workers?

Build a smaller container in worker main with job-specific deps - share pool singleton.

Is `new` in use cases ever OK?

For value objects and pure domain types yes. For repositories and HTTP clients, no - inject them.

What is the composition root in serverless?

Lambda handler top-level: cold start builds container once, reuse across invocations in same instance.

Modularity Basics - layering intro
Use Cases & Services - what gets injected
Repository Pattern - common port implementation
NestJS Dependency Injection - Nest-specific depth
Hexagonal Architecture in Node - ports and adapters

NestJS Documentation - Progressive Node.js framework docs.
Node.js Best Practices (GitHub) - Curated production best practices.
DEV Community – Node.js - Community articles and discussions.
Node.js Design Patterns, 4th Edition - Production-grade application patterns.
Node.js Design Patterns (author site) - Author site for Design Patterns.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Recipe

Quick-reference recipe card - copy-paste ready.

// Manual DI - composition root
const orders = new PostgresOrderRepository(pool);
const createOrder = new CreateOrder(orders);
app.post("/orders", (req, res) => createOrder.execute(req.body));

// Awilix - container
import { createContainer, asClass, asValue } from "awilix";
const container = createContainer();
container.register({
  pool: asValue(pool),
  orderRepository: asClass(PostgresOrderRepository).singleton(),
  createOrder: asClass(CreateOrder).singleton(),
});

When to reach for this:

Tests need to swap repositories without module mocks
Multiple entry points (HTTP, worker, CLI) share use cases
Constructor parameter lists grow past 4-5 dependencies
Team adopts NestJS and wants decorator-based wiring

Working Example

// application/create-order.ts
import type { OrderRepository } from "../domain/ports/order-repository";
 
export class CreateOrder {
  constructor(private readonly orders: OrderRepository) {}
 
  async execute(input: { customerId: string; sku: string; qty: number }) {
    const order = { id: crypto.randomUUID(), ...input, status: "pending" as const };
    await this.orders.save(order);
    return order;
  }
}
 
// manual composition root
import express from "express";
import { Pool } from "pg";
import { PostgresOrderRepository } from "./infrastructure/postgres-order-repository";
import { CreateOrder } from "./application/create-order";
 
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const createOrder = new CreateOrder(new PostgresOrderRepository(pool));
 
const app = express();
app.use(express.json());
app.post("/orders", async (req, res) => {
  res.status(201).json({ data: await createOrder.execute(req.body) });
});
 
// Awilix alternative - src/container.ts
import { createContainer, asClass, asValue, InjectionMode } from "awilix";
 
export function buildContainer(pool: Pool) {
  const container = createContainer({ injectionMode: InjectionMode.CLASSIC });
  container.register({
    pool: asValue(pool),
    orderRepository: asClass(PostgresOrderRepository).singleton(),
    createOrder: asClass(CreateOrder).singleton(),
  });
  return container;
}
 
// Resolve in main
// const { createOrder } = buildContainer(pool).cradle;

What this demonstrates:

CreateOrder depends on OrderRepository interface only
Manual wiring is explicit and grep-friendly
Awilix registers classes and resolves graph automatically
Both patterns keep framework code out of use cases

Deep Dive

How It Works

Injection: dependencies passed in (constructor, factory param, or container resolve)
Composition root: main.ts or container.ts - the only place that news concrete adapters
Lifetime: singleton (one DB pool) vs transient (per-request) - default singleton for repos
NestJS: @Injectable() providers, constructor injection, module imports/exports

Pattern Comparison

Pattern	Pros	Cons	Best for
Manual	Obvious, zero magic, fast tests	Verbose at scale	<15 bindings
Awilix	Auto-wiring, scoped lifetimes	Learning curve, runtime resolve	Express/Fastify midsize
Nest DI	First-class modules, testing utils	Decorator opinion, bootstrap cost	Nest-standard teams
`proxyquire`/module mocks	Quick hack	Brittle, breaks encapsulation	Avoid in production code

NestJS Sketch

@Injectable()
export class CreateOrder {
  constructor(private readonly orders: OrderRepository) {}
}
 
@Module({
  providers: [
    CreateOrder,
    { provide: "OrderRepository", useClass: PostgresOrderRepository },
  ],
  controllers: [OrdersController],
})
export class OrdersModule {}

TypeScript Notes

// Token-based injection without string magic - use symbols or interfaces
export const OrderRepositoryToken = Symbol("OrderRepository");
type OrderRepository = import("../domain/ports/order-repository").OrderRepository;

Gotchas

Service locator anti-pattern - container.resolve scattered in routes. Fix: Resolve once at boot; inject into handlers.
Global singleton module - export const db = new Pool(). Fix: Register in composition root; pass to repos.
Circular provider dependencies in Awilix - A needs B needs A. Fix: Extract shared port or event.
Over-using Nest for 5 routes - DI ceremony without team buy-in. Fix: Manual DI until Nest is org standard.
Transient pool per request - Exhausts DB connections. Fix: Singleton pool, transient repos only if needed.

Alternatives

Alternative	Use When	Don't Use When
Manual factory functions	Small Fastify services	30+ use cases with shared deps
`tsyringe`	Decorator DI without Nest	Team avoids decorators
Pure functions + deps param	Functional style	Large graphs with shared config
No DI - import singletons	Throwaway scripts	Long-lived APIs

FAQs

When should I adopt Awilix over manual?

When you have 10+ classes to wire and repeated new chains in main.ts. Before that, manual is clearer.

Does Fastify have built-in DI?

No first-class DI. Use manual, Awilix, or fastify-decorators with care.

How do I test Awilix containers?

Request-scoped dependencies in Express?

Use AsyncLocalStorage or per-request container child scope in Awilix (scopePerRequest plugin pattern).

Nest REQUEST scope performance?

REQUEST-scoped providers add overhead. Default singleton; use REQUEST only for true per-request state.

Can I mix manual and Awilix?

Yes during migration. New modules register in Awilix; legacy stays manual until touched.

Interface injection without runtime types?

TypeScript interfaces erase at runtime. Use abstract class, token symbol, or string token in Nest.

How does DI work in workers?

Build a smaller container in worker main with job-specific deps - share pool singleton.

Is `new` in use cases ever OK?

For value objects and pure domain types yes. For repositories and HTTP clients, no - inject them.

What is the composition root in serverless?

Lambda handler top-level: cold start builds container once, reuse across invocations in same instance.

Modularity Basics - layering intro
Use Cases & Services - what gets injected
Repository Pattern - common port implementation
NestJS Dependency Injection - Nest-specific depth
Hexagonal Architecture in Node - ports and adapters

NestJS Documentation - Progressive Node.js framework docs.
Node.js Best Practices (GitHub) - Curated production best practices.
DEV Community – Node.js - Community articles and discussions.
Node.js Design Patterns, 4th Edition - Production-grade application patterns.
Node.js Design Patterns (author site) - Author site for Design Patterns.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Dependency Injection Patterns

Search Documentation

Dependency Injection Patterns