AI agent instructions

Needle DI ships machine-readable documentation, so AI coding agents can work with it without guessing APIs.

Documentation sources

When working on Needle DI-related code, always verify against the current Needle DI documentation. Prefer current documentation over assumptions from memory.

Source	Use it for
/llms.txt	Compact index of all documentation pages
/llms-full.txt	The complete documentation as a single Markdown file
/<page>.md (e.g. /concepts/binding.md)	The Markdown source of a single page

For external agents, use the absolute URLs:

• https://needle-di.io/llms.txt
• https://needle-di.io/llms-full.txt

Every documentation page also has Copy as Markdown and Download as Markdown buttons, so you can paste a page straight into a chat.

Additional sources:

• @needle-di/core on npm
• @needle-di/core on JSR, which contains the generated API reference
• The source code on GitHub

Guidance for agents

The following rules cover the mistakes LLMs most often make with Needle DI. They also apply when generating code based on knowledge of other DI libraries such as Angular, NestJS or InversifyJS.

Do

• Use inject(Token) as a default parameter value in constructors, initializers or factory functions.
• Use @injectable() for auto-binding services with a zero-argument constructor signature.
• Use bind() with a provider when a service needs explicit configuration.
• Use InjectionToken<T> for values that are not classes, and pass a factory when the token should be tree-shakeable.
• Use injectAsync() and getAsync() for asynchronous factory providers.
• Use container.runInInjectionContext() to call inject() from a plain function that the container did not construct.
• Use { optional: true }, { multi: true } and { lazy: true } instead of hand-rolled alternatives.

Don't

• Don't install or import reflect-metadata or any other reflection library.
• Don't enable experimentalDecorators or emitDecoratorMetadata, these are legacy TypeScript decorators.
• Don't use parameter decorators such as @Inject() or @Injectable() from other frameworks, Needle DI has no parameter decorators.
• Don't call inject() outside an injection context, use container.get() or container.runInInjectionContext() there instead.
• Don't call inject() after an await inside container.runInInjectionContext(), the injection context is only active while the given function runs synchronously.
• Don't create a new Container per service, bootstrap a single container (or use child containers for scoping).

Canonical example

import { Container, inject, injectable } from "@needle-di/core";

@injectable()
class FooService {}

@injectable()
class BarService {
  constructor(private fooService = inject(FooService)) {}
}

const container = new Container();
const barService = container.get(BarService);