This page documents the 0.4 release candidates of @nexusdi/core. The newest on npm is 0.4.0-rc.1. The documentation for 0.3.2, the current release, is at nexus.js.org. Try the release candidate.

NexusDI vs Other Containers

When choosing a dependency injection container, the primary trade-offs are typically bundle size, startup performance, and the ability to detect wiring mistakes.

NexusDI is compared here against four other TypeScript containers using a standardized benchmark harness. Every figure on this page is derived from actual measurements of the same eight-provider graph. The page renders each figure from the harness’s results files at build time. Understanding Benchmark Measurements states the method behind each one.

Performance and Footprint

The performance table below compares bundle size, cold-start time, and resolution speed.

Bundle Size: The minified and gzipped esbuild bundle size.
Startup Time: Cold start of a fresh Node process.
Resolve Speed: Time for a single transient resolution on a ready container.
Build Time: The library’s fastest passing build of a 200-class graph under a toolchain its documentation names.

Each library appears in the variant its own documentation teaches. Focus or hover a figure for its spread and, on another library’s row, the paired ratio to NexusDI with its interval. A ratio below 1 means NexusDI took less time, and an interval that contains 1 is no measured difference.

Performance comparison

Timings run 2026-10-01-8824502 on INTEL(R) XEON(R) PLATINUM 8573C, with @nexusdi/core 0.4.0-rc.0. Each figure is a median; focus or hover it for the spread. How the benchmarks are measured
Library	Bundle size (min+gzip)	Startup	Resolve	Build time
NexusDI plain	19.0 kB	53.1 ms	124 ns	264 ms (bun)
InversifyJS decorated	22.0 kB	81.8 ms	66.3 ns	518 ms (tsgo)
tsyringe decorated	9.8 kB	34 ms	193 nsnoisy	486 ms (tsgo)
awilix plain	3.9 kB	43.6 ms	131 nsnoisy	261 ms (bun)
needle-di decorated	3.4 kB	27.7 ms	not measured: needle-di documents singletons only.	263 ms (bun)

Toolchain Flexibility

Many DI libraries rely on emitDecoratorMetadata, which requires specific compiler flags that not every toolchain supports. In the matrix below, the metadata-based variants fail to compile under Node’s type stripping, and tsyringe’s fails at runtime under esbuild. Every variant passes under Bun and Deno.

NexusDI avoids this by using static deps. Because static deps needs no compiler-emitted metadata, it passes under every toolchain in the matrix. The @nexusdi/decorators variant uses standard decorators, which plain Vite and Node’s type stripping cannot compile.

A cell that does not pass keeps its first error line in a tooltip and links the toolchain’s own page when that page documents the limitation. InversifyJS’s getting-started page and tsyringe’s README set experimentalDecorators and emitDecoratorMetadata for their decorated setups. awilix and needle-di document setups that use no decorator metadata (inversify 8.2.3, tsyringe 4.10.0, awilix 13.0.5, needle-di 1.2.1; read 2026-09-30).

Toolchain matrix

The outcome of Meridian-8 for each library and variant under each toolchain, with @nexusdi/core 0.4.0-rc.0.
Library and variant	tsc	tsgo	esbuild	swc	babel	vite	vite8+babel-plugin	bun	deno	node-strip-types
awilix plain	pass	pass	pass	pass	pass	pass	pass	pass	pass	pass
InversifyJS decorated	pass	pass	pass	pass	pass	pass	pass	pass	pass	compile error documented
InversifyJS decorated-explicit	pass	pass	pass	pass	compile error	pass	compile error	pass	pass	compile error documented
InversifyJS plain	pass	pass	pass	pass	pass	pass	pass	pass	pass	pass
needle-di decorated	pass	pass	pass	pass	pass	compile error documented	pass	pass	pass	compile error documented
needle-di plain	pass	pass	pass	pass	pass	pass	pass	pass	pass	pass
NexusDI decorated	pass	pass	pass	pass	pass	compile error documented	pass	pass	pass	compile error documented
NexusDI plain	pass	pass	pass	pass	pass	pass	pass	pass	pass	pass
tsyringe decorated	pass	pass	runtime error documented	pass	pass	pass	pass	pass	pass	compile error documented
tsyringe decorated-explicit	pass	pass	pass	pass	compile error	pass	compile error	pass	pass	compile error documented
tsyringe plain	pass	pass	pass	pass	pass	pass	pass	pass	pass	pass

Wiring-Mistake Detection

Most containers are “optimistic”. They assume the graph is correct and only fail at runtime when a missing dependency is requested. This can lead to crashes in production on rarely-used code paths.

NexusDI is “pessimistic.” It validates the entire module graph during the Nexus.create phase. If a dependency is missing, Nexus.create reports it before any constructor runs. One error lists every problem it found (Errors).

The probe table adds one mistake at a time to the graph and shows where each library reports it.

Wiring-mistake probes

When each library reports a wiring mistake in Meridian-8, with @nexusdi/core 0.4.0-rc.0.
Mistake	NexusDI	InversifyJS	tsyringe	awilix	needle-di
A provider is never registered	container creation	first resolve	first resolve	first resolve	first resolve
Two providers depend on each other	container creation	first resolve	never	first resolve	first resolve
A singleton depends on a scoped provider	container creation	not applicable	never	first resolve	not applicable
A dependency has the wrong type	type check	never	never	type check	never
A missing provider and a cycle together	container creation, names 2 of 2	first resolve, names 1 of 2	first resolve, names 1 of 2	first resolve, names 1 of 2	first resolve, names 1 of 2

Lifecycle and Disposal Comparison

Managing resources (like database pools) is critical. NexusDI implements a strict reverse-creation order for disposal and uses SuppressedError to ensure every resource is closed, even if some failures occur. Lifecycle and Disposal explains why each row matters.

A cell says what the library does without extra plugins unless it names one.

Feature	NexusDI	InversifyJS	tsyringe	awilix	needle-di	TypeDI	NestJS
Dependency-ordered `onInit`	Yes	Per instance, on first resolve	No	No	No	No	Yes
Reverse-order Disposal	Yes	No	No	No	n/a	No	Yes
Reports all disposal failures	Yes	No	No	No	n/a	No	Logged
Scopes own transients	Yes	No	Yes	No	n/a	No	No
Disposes factory results	Yes	Partial	No	With `.disposer()`	n/a	Yes	Yes

The harness does not measure this table: it is read from each library’s source and documentation, and the notes are in specs/2026-10-03-lifecycle-comparison-research.md.

The detailed version of the same comparison, row by row:

	NexusDI	InversifyJS	tsyringe	awilix	needle-di	TypeDI	NestJS
Startup hook awaited in dependency order	Yes, `onInit` before `create` resolves	Per instance on first resolve, awaited through `getAsync`	No hook	No hook	No hook	No hook	Yes, `onModuleInit`
Container disposal	`Symbol.asyncDispose`	`unbindAllAsync()`	`dispose()`	`dispose()`	None	`reset()` calls `destroy()`	`app.close()`
Supports `Symbol.dispose` and `Symbol.asyncDispose`	Both	Both, with `@inversifyjs/plugin-dispose`	No	No	No	No	No
Disposal order	Reverse creation	Unspecified, plugin runs fewest dependents first	Creation order, so dependencies first	All at once	n/a	Registration order	Reverse of startup
All disposer failures reported	Yes, `SuppressedError` chain	No, first error	No, first error	No, first error	n/a	No, errors ignored	Logged, not thrown
Keeps going after a failure	Yes	Plugin stops at the first	Async failures only, a sync throw skips the rest	Yes	n/a	Yes	Yes
Scopes own transients	Yes	No	Yes, by the container that resolved it	No	n/a	No	No, request-scoped providers get no hooks
Disposes factory results	Yes	Only with `onDeactivation`	No	Yes, with `.disposer()`	n/a	Yes	Yes
Leaves `useValue` objects alone	Yes	Yes, unless `onDeactivation` is set	Yes	Yes	n/a	Yes	No, hooks run on them

NestJS has the most complete startup story of the six. It awaits hooks module by module and by dependency depth inside a module, runs shutdown in the reverse order and logs every failure. Its hooks are provider methods, and a Nest application is not an AsyncDisposable. tsyringe disposes every disposable instance it builds, transients included. awilix awaits any promise a .disposer() returns, and a container disposes only its own cache, never its scopes. InversifyJS has @postConstruct and @preDestroy, and with its dispose plugin it supports await using. needle-di and TypeDI document no startup hook and no awaited disposal.

Versions read on 2026-10-03: inversify 8.2.3 (with @inversifyjs/plugin-dispose 0.4.7), tsyringe 4.10.0, awilix 13.0.5, needle-di 1.2.1, TypeDI 0.10.0, @nestjs/core 12.1.2. Sources: the published packages’ code, InversifyJS container API , tsyringe disposable instances , awilix disposing , needle-di docs and NestJS lifecycle events .

Containers Left Out

TypeDI is left out of the measurements: its last release, 0.10.0, was published on 2021-01-15 (npm ). NestJS is a framework with its own container, so it is left out too.

Conclusion

If you are building a large-scale application where reliability, startup speed, and toolchain flexibility are priorities, NexusDI’s static validation and lightweight core make it a strong choice. For those already using the NestJS framework, its built-in container already wires your services, and NexusDI would add a second container beside it. See When to skip NexusDI.

Break and Fix a Benchmark Figure

Every figure on this page comes from the harness, and a guard keeps it that way. The <Figure> component renders one result inline in a sentence, and the doc-benchmark-figures guard fails on a path the results do not hold.

Try it: In apps/docs/content/index.mdx, change the figure’s path from size.nexusdi.plain.esbuild.gzip to size.nexusdi.plain.esbuild.brotli, and run the guard:


npx nx test @nexusdi/repo-checks -- doc-benchmark-figures

The guard fails and names the key the results lack. Type a size with its unit into a sentence on the same page, and the guard fails on that sentence too, because a figure in prose comes only from the harness. Restore the path and delete the sentence, and the guard passes.

How This Comparison Was Measured

The NexusDI maintainer wrote the harness and measured these results, and has an interest in them. Each library’s fixture follows its own documentation, and Understanding Benchmark Measurements lists what was pinned, what was tested, what was left out, and how to report a fixture that departs from a library’s documentation.

Measured with

Libraries: NexusDI 0.4.0-rc.0InversifyJS 8.2.3 with a decorator metadata polyfilltsyringe 4.10.0 with a decorator metadata polyfillawilix 13.0.5needle-di 1.2.1
Toolchains: tsc 6.0.3tsgo 7.0.2esbuild 0.28.2swc 1.16.2babel 8.0.6vite 8.3.0vite8+babel-plugin 8.3.0bun 1.4.2deno 2.9.6node-strip-types 24.20.0bundlers: esbuild 0.28.2, rollup 4.63.4
Runtime: Node 24.20.0
Runner: INTEL(R) XEON(R) PLATINUM 8573C, 4 cores, 16 GB, Linux, GitHub-hosted
Timings run: 2026-10-01, seed 36891702544, core commit 8824502
Results files: matrix.json at a9231afprobes.json at a9231afsize.json at f699eb1build.json at 20d5e27timings/2026-10-01-8824502.json at 20d5e27