A universal, lightweight and type-safe dependency injection container for TypeScript. Heavily inspired by Angular's DI system, but designed to work in any environment (Node.js, Bun, Deno, browsers, and more).

• Type-Safe – Excellent type inference
• Lightweight – Zero dependencies, minimal bundle size
• Flexible – Classes, factories, values, and aliases
• Optional decorators – Injectable classes with @NodeInjectable() (or the @Service() / @Scoped() shorthands)
• Multi-Tokens – Built-in multi-provider support
• Lifecycle hooks – Graceful container destruction and resource cleanup
• Plugin System – Extensible architecture with custom middlewares, scanners, and diagnostics
• TestKit – Unit testing and mocking utilities for any testing framework
• Universal – Node.js, Bun, Deno, browser, and Electron

Please check out the migration guide for details on what's new and how to upgrade from v1.

npm install @illuma/core

Install the bundled Agent Skill so your AI coding agent follows Illuma's conventions:

npx skills add git-illuma/core

The skill lives at skills/illuma-core/ and is installed into your project's agent directory (e.g. .claude/skills/).

ES2020+. In practice: Node.js 14+, Bun, Deno, and browsers from early 2020 onwards (Chrome 80+, Firefox 74+, Safari 13.1+).

That is a checked floor rather than an aspiration. The npm bundle is pinned to it (target: 'es2020'), and the sources are written to it too, so the JSR package — which publishes src/ rather than the bundle — asks no more of you than npm does.

Two notes:

• globalThis is a runtime global, not syntax. It is the one thing a transpiler cannot supply for you, so an engine older than ES2020 needs a polyfill for it in addition to compiling the bundle down. That configuration is not tested here.
• weakParentLink is the only thing that reaches past the floor. Where WeakRef or FinalizationRegistry is missing it logs a warning once and falls back to the default strong parent link, so it degrades instead of breaking. Nothing else in the library touches either.

import { NodeContainer, NodeInjectable, nodeInject } from '@illuma/core';

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

@NodeInjectable()
class UserService {
  private readonly logger = nodeInject(Logger);

  public getUser(id: string) {
    this.logger.log(`Fetching user ${id}`);
    return { id, name: 'John Doe' };
  }
}

const container = new NodeContainer();
container.provide([Logger, UserService]);
container.bootstrap();

const userService = container.get(UserService);

Note: Example above requires experimentalDecorators and emitDecoratorMetadata in tsconfig. See Getting Started for decorator-free alternatives.

import { NodeToken, MultiNodeToken, NodeContainer } from '@illuma/core';

// Single-value token
const CONFIG = new NodeToken<{ apiUrl: string }>('CONFIG');

// Multi-value token (when injected, returns array)
const PLUGINS = new MultiNodeToken<Plugin>('PLUGINS');

const container = new NodeContainer();

container.provide([
  // Equivalent to:
  // { provide: CONFIG, value: { apiUrl: 'https://api.example.com' } }
  CONFIG.withValue({ apiUrl: 'https://api.example.com' }),

  // Equivalent to:
  // { provide: PLUGINS, useClass: AnalyticsPlugin }
  PLUGINS.withClass(AnalyticsPlugin),

  // Equivalent to:
  // { provide: PLUGINS, useClass: LoggingPlugin }
  PLUGINS.withClass(LoggingPlugin),
]);

container.bootstrap();

const config = container.get(CONFIG);    // { apiUrl: string }
const plugins = container.get(PLUGINS);  // Plugin[]: [AnalyticsPlugin, LoggingPlugin]

See Tokens Guide for more details.

// Class provider
container.provide(MyService);

// Value provider
container.provide({ provide: CONFIG, value: { apiUrl: '...' } });

// Factory provider
container.provide({ provide: DATABASE, factory: () => {
  // You can use nodeInject inside factories!
  const env = nodeInject(ENV);
  return createDatabase(env.connectionString);
} });

// Class provider with custom implementation
container.provide({ provide: DATABASE, useClass: DatabaseImplementation });

// Alias provider
container.provide({ provide: Database, alias: ExistingDatabase });

See Providers Guide for details.

import { createTestFactory } from '@illuma/core/testkit';

const createTest = createTestFactory({
  target: UserService,
  provide: [{ provide: Logger, useClass: MockLogger }],
});

it('should fetch user', () => {
  const { instance } = createTest();
  expect(instance.getUser('123')).toBeDefined();
});

See Testing Guide for examples.

Illuma supports plugins! Check these out:

• @illuma/reflect – Constructor metadata and property decorator injection support

See Plugins Guide for creating your own plugins.

Thank you for considering contributing to Illuma! I deeply appreciate your interest in making this project better.

Anyways, to get you started, please take a look at the Contributing Guide for guidelines on how to setup development environment, run tests, and submit pull requests.

MIT

Created by bebrasmell

• NPM
• GitHub
• Issues