Quick Start

This guide demonstrates building a modular application with OrderModule and UserModule, showing how modules import each other and share dependencies with full type safety.

1. Create OrderModule with its definitions

Define OrderModule with typed providers and export orderService for other modules:

// order.module.ts
import { createModule, type ModuleDef } from "awilixify";

import { OrderService } from "./order.service";

// Define OrderModule
type OrderModuleDef = ModuleDef<{
  providers: {
    orderService: OrderService;
  };
  exportKeys: ["orderService"];
}>;

export const OrderModule = createModule<OrderModuleDef>({
  name: "OrderModule",
  providers: {
    orderService: OrderService,
  },
  exports: ["orderService"],
});

2. Create UserModule with its definitions

Define UserModule and import OrderModule:

// user.module.ts
import { createModule, type ModuleDef } from "awilixify";

import { OrderModule } from "../order/order.module";
import { UserService } from "./user.service";
import { EmailService } from "./email.service";

// Define UserModule that imports OrderModule
type UserModuleDef = ModuleDef<{
  providers: {
    userService: UserService;
    emailService: EmailService;
  };
  imports: [typeof OrderModule];
}>;
// Available deps within module
export type UserModuleDeps = UserModuleDef["deps"];

export const UserModule = createModule<UserModuleDef>({
  name: "UserModule",
  imports: [OrderModule],
  providers: {
    userService: UserService,
    emailService: EmailService,
  },
});

3. Create GlobalModule to share dependencies

Create a global module for app-wide dependencies like http framework instance, logger... Use declare module to make global dependencies available in Deps type to all modules:

// global.module.ts
import {
  createModule,
  type ModuleDef,
  type InferGlobalDependencies,
} from "awilixify";
import type { Express } from "express";

export type GlobalModuleDef = ModuleDef<{
  providers: {
    app: Express;
  };
  exportKeys: ["app"];
}>;

export function GlobalModule(app: Express) {
  return createModule<GlobalModuleDef>({
    name: "GlobalModule",
    providers: {
      app,
    },
    exports: ["app"],
  });
}

// Extend GlobalDependencies to make global module exports available everywhere
declare module "awilixify" {
  interface GlobalDependencies extends InferGlobalDependencies<GlobalModuleDef> {}
}

4. Instantiate DIContext with AppModule

Instantiate DIContext with root module and global modules:

// app.module.ts
import { DIContext } from "awilixify";

import { UserModule } from "./user.module";
import { GlobalModule } from "./global.module";

type AppModuleDef = ModuleDef<{
  imports: [typeof UserModule];
}>;

export const AppModule = createModule<AppModuleDef>({
  name: "AppModule",
  imports: [UserModule],
});

// initialize your http framework instance
const app = express();

// Instantiate DIContext with root module and global modules
DIContext.create(AppModule, {
  globalModules: [GlobalModule(app)],
});

// run your http framework service as usual
app.listen(3000);

5. Type-safe dependency injection from module definition

Use ModuleDef['deps'] as single source of truth to get automatic type inference for all available dependencies in your service constructors.
This includes:

• module providers
• imported module exported providers
• exported providers from global modules
• module mediator instance (if query/command handlers are registered)

// user.service.ts
import { UserModuleDeps } from "./user.module";

class UserService {
  constructor(
    // From UserModule providers
    private readonly emailService: UserModuleDeps["emailService"],
    // From OrderModule providers
    private readonly orderService: UserModuleDeps["orderService"],
    // From global module exports
    private readonly app: UserModuleDeps["app"],
  ) {}

  async notifyWithOrders(to: string) {
    this.emailService.s


    this.orderService.f

  }
}

6. Use controllers with any framework

Route definition happens within registerRoutes controller method(or with native ES Stage 3 decorators). It allows integration with any HTTP framework you pass through global dependencies (Express, Fastify, Hono, Koa, etc.).
This is especially useful for gradually migrating existing applications to a modular architecture without a full rewrite

// user.controller.ts
import type { Express, Request, Response } from "express";
import { Controller } from "awilixify";

import { UserModuleDeps } from "./user.module.ts";

class UserController implements Controller {
  constructor(
    private readonly userService: UserModuleDeps["userService"],
    // taken from global module exports
    private readonly app: UserModuleDeps["app"],
  ) {}
  registerRoutes() {
    // Direct framework API - no abstraction layer
    app.get("/users/:id", async (req: Request, res: Response) => {
      const user = await this.userService.getUser(req.params.id);
      res.json(user);
    });
  }
}

// user.module.ts - Add controller to module
export const UserModule = createModule<UserModuleDef>({
  name: "UserModule",
  imports: [OrderModule],
  providers: {
    userService: UserService,
    emailService: EmailService,
  },
  controllers: [UserController], // Register controller
});