Registry / web-framework / tsyringe

tsyringe

JSON →
library4.10.0jsnpmunverified

TSyringe is a lightweight dependency injection (DI) container for JavaScript and TypeScript, primarily focusing on constructor injection. Currently at stable version 4.10.0, it is actively maintained and backed by Microsoft. Its release cadence appears to be feature-driven, with recent updates (v4.4.0) adding interception and transformation capabilities. Key differentiators include its strong integration with TypeScript decorators (`@injectable`, `@singleton`, `@inject`), its ability to handle complex dependency graphs including circular dependencies with a `delay` helper, and its provision for both class-based and interface-based injection using tokens. It requires `reflect-metadata` for decorator-based type reflection and specific `tsconfig.json` settings.

npm install tsyringe
INSTALL
IMPORT
SIG · TSYRINGE
T
tsyringe
web-frameworkjavascriptv4.10.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

injectable
import { injectable } from 'tsyringe';
const { injectable } = require('tsyringe');
Class decorator for enabling dependency injection.
container
import { container } from 'tsyringe';
import Container from 'tsyringe';
The global container instance for registering and resolving dependencies.
singleton
import { singleton } from 'tsyringe';
import { Singleton } from 'tsyringe';
Class decorator to register a class as a singleton.
inject
import { inject } from 'tsyringe';
import { Inject } from 'tsyringe';
Parameter decorator used for injecting dependencies by token, especially useful for interfaces or primitive values.

Demonstrates basic setup, interface-based dependency injection, and singleton registration.

import "reflect-metadata"; // Must be imported ONCE at the very top of your application entry point import { container, injectable, inject, singleton } from "tsyringe"; // 1. Define an interface for abstraction interface IDatabaseService { connect(): void; getData(query: string): string; } // 2. Implement the interface and mark as injectable @injectable() class RealDatabaseService implements IDatabaseService { connect() { console.log("Connected to a real database."); } getData(query: string): string { return `Data for: ${query} from RealDatabase`; } } // 3. Define a service that depends on IDatabaseService @injectable() class DataProcessorService { constructor(@inject("IDatabaseService") private dbService: IDatabaseService) { this.dbService.connect(); } processUserData(userId: string): string { const query = `SELECT * FROM users WHERE id = ${userId}`; return `Processing user data: ${this.dbService.getData(query)}`; } } // 4. Register the interface with its implementation in the container container.register<IDatabaseService>("IDatabaseService", { useClass: RealDatabaseService, }); // 5. Resolve the DataProcessorService const dataProcessor = container.resolve(DataProcessorService); console.log(dataProcessor.processUserData("123")); // 6. Example of a singleton service @singleton() class AppConfig { public readonly API_KEY = process.env.API_KEY ?? 'default-api-key'; constructor() { console.log("AppConfig initialized (should only happen once for singleton)."); } } const config1 = container.resolve(AppConfig); const config2 = container.resolve(AppConfig); console.log(`API Key: ${config1.API_KEY}`); console.log(`Are config instances identical? ${config1 === config2}`); /* NOTE: Ensure your tsconfig.json includes: { "compilerOptions": { "experimentalDecorators": true, "emitDecoratorMetadata": true } } */
Debug
Known issues
gotchaTSyringe heavily relies on TypeScript's decorator metadata. You must enable `experimentalDecorators` and `emitDecoratorMetadata` in your `tsconfig.json` under `compilerOptions`.
fix
Add or ensure the following in your `tsconfig.json`: `"compilerOptions": { "experimentalDecorators": true, "emitDecoratorMetadata": true }`
affects: >=1.0.0
gotchaA polyfill for the Reflect API (e.g., `reflect-metadata`) is a mandatory runtime dependency. It must be imported exactly once in your application's entry point, *before* any TSyringe code or decorated classes are loaded.
fix
Install `reflect-metadata` (`npm install reflect-metadata`) and add `import "reflect-metadata";` as the very first line in your main application file (e.g., `main.ts` or `index.ts`).
affects: >=1.0.0
gotchaIf you are using Babel (e.g., in a React Native project), you must install and configure `babel-plugin-transform-typescript-metadata` to ensure TypeScript metadata is correctly emitted.
fix
Install `babel-plugin-transform-typescript-metadata` (`npm install --save-dev babel-plugin-transform-typescript-metadata`) and add it to your Babel configuration's `plugins` array.
affects: >=1.0.0
gotchaHandling circular dependencies requires using the `delay` helper function when registering or injecting. Without it, you will encounter runtime errors or `undefined` dependencies.
fix
Wrap the dependency registration or injection with `delay(() => DependencyClass)` or `delay(() => container.resolve(DependencyClass))`.
affects: >=1.0.0
Errors
Common errors & fixes
No matching binding found for token: [object Object]
A class or interface token was requested from the container but was never registered, or the `@injectable()` decorator was omitted from a class intended for injection.
fix
Ensure that all classes intended for injection are decorated with `@injectable()` and that any interfaces or custom tokens have a corresponding `container.register()` call.
TypeError: Reflect.metadata is not a function
The `reflect-metadata` polyfill was either not imported, imported incorrectly, or imported after TSyringe or decorated classes were loaded.
fix
Verify `reflect-metadata` is installed (`npm install reflect-metadata`) and that `import "reflect-metadata";` is the absolute first line in your application's entry point.
SyntaxError: Decorators are not enabled.
The TypeScript compiler options `experimentalDecorators` or `emitDecoratorMetadata` are not correctly set in `tsconfig.json`, or Babel is not configured for metadata emission.
fix
Check your `tsconfig.json` for `"experimentalDecorators": true` and `"emitDecoratorMetadata": true`. If using Babel, ensure `babel-plugin-transform-typescript-metadata` is installed and configured in your Babel plugins.
Upgrade
Version history
4.10.0latest on npm
Audit
Dependencies
reflect-metadatarequiredRequired runtime polyfill for decorator-based type reflection, must be imported once.
Agent activity
12 hits · last 30 days
node
12
Resources
tsyringe — npm install tsyringe · libregistry