Installation

The core package has no runtime dependencies and works with SWC and TypeScript's decorator support.

Requirements

TypeScript 5.0 or higher
SWC or TypeScript compiler with decorator support enabled

Scaffold an app (recommended)

The fastest path is the app CLI:

bun x @di-framework/cli init my-api
cd my-api && bun install && bun run dev

That writes a tsconfig.json with @di-framework/tsc (plugins), @di-framework/cli, and sample src/index.ts (ttsc and TypeScript 7+ come with @di-framework/tsc). Scripts call di-framework build/di-framework check (which run ttsc). Runtime parameter checks are injected on emit (bun run build). See CLI for check/build and Runtime type checks.

Install the Package

npm install @di-framework/core

or with yarn:

yarn add @di-framework/core

or with bun:

bun add @di-framework/core

Configuration

TypeScript Configuration

Ensure your tsconfig.json has the following settings:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": false,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

Apps from di-framework init also include plugins: [{ "transform": "@di-framework/tsc" }] and emit via ttsc. For manual setup of runtime parameter checks, see Runtime type checks.

SWC Configuration

If you're using SWC, ensure your .swcrc has decorator support enabled:

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true
    },
    "transform": {
      "legacyDecorator": true,
      "decoratorMetadata": false
    }
  }
}

No Additional Dependencies

The decorators are fully integrated with SWC's native support - no need for reflect-metadata or any other polyfill. This keeps your bundle size small and your dependencies minimal.

Import paths and container singleton

Always import from the scoped package @di-framework/core/* to ensure a single global container instance. Mixing different import IDs (e.g., di-framework/* or relative paths to sources) can load a second copy of the library and create a second global container instance.

Correct:

import { useContainer } from '@di-framework/core/container';
import { Container, Component } from '@di-framework/core/decorators';

Avoid:

// Wrong: unscoped package id
import { useContainer } from 'di-framework/container';
// Wrong: relative source path
import { Container } from '../../di-framework/decorators';

Verify Installation

Create a simple test file to verify the installation:

import { Container } from '@di-framework/core/decorators';
import { useContainer } from '@di-framework/core/container';

@Container()
class TestService {
  getMessage() {
    return 'di-framework is working!';
  }
}

const container = useContainer();
const service = container.resolve(TestService);
console.log(service.getMessage());

Run the file with your TypeScript runner (ts-node, tsx, bun, etc.):

bun run test.ts
# Output: di-framework is working!

Version 6 package sources

Version 6 publishes from several repositories. Core application packages (@di-framework/core, @di-framework/http, and the other packages in the core monorepo) publish at 6.x from di-framework/di-framework. AI packages, the operated platform, bindings, and first-party CLI extensions publish from their own repositories at 6.x:

Package	Repository
`@di-framework/core`, `@di-framework/http`, `@di-framework/cli`, and companion core packages	di-framework/di-framework
`@di-framework/ai`, `@di-framework/ai-utils`	di-framework/ai
`@di-framework/platform`, `@di-framework/bindings`, `@di-framework/cloudfoundry`, `@di-framework/cloudflare`	di-framework/platform
`@di-framework/cli-plugin-platform`, `@di-framework/cli-plugin-ai`	di-framework/cli-extensions

Install platform and AI extensions with di-framework extensions install platform and di-framework extensions install ai. Platform commands use the platform group (including platform cluster for managed Pulumi targets). See AI CLI and Platform. Sample apps live in di-framework/examples, including platform-examples for a single-command local platform deploy. This is distinct from kube examples-apps, its application verification workspace.

@di-framework/platform 6.0.7 includes blobstore, egress, tenant kubeconfigs, and the HTTP gateway. di-framework-kube still installs @di-framework/[email protected] unless you pass --platform-package. See Kubernetes with di-framework-kube.

Optional Packages

The core package stands alone. Companion packages add data access, HTTP, GraphQL, events, sockets, RPC, configuration, authentication, and AI support:

Package	Docs
`@di-framework/cli`	CLI
`@di-framework/tsc`	Runtime type checks (default in `init`)
`@di-framework/biome`	Biome plugins — GritQL rules for framework mistakes
`@di-framework/codegen`	Schema codegen — `di-framework generate` surfaces from schema manifests
`@di-framework/repo`	Repositories, including the wasmCloud PostgreSQL codec
`@di-framework/http`	HTTP Router
`@di-framework/graphql`	GraphQL
`@di-framework/events`	Events
`@di-framework/queues`	Queues — durable jobs (latest / EAP)
`@di-framework/actors`	Actors — local virtual actors (latest / EAP)
`@di-framework/socket`	Sockets
`@di-framework/rpc`	RPC
`@di-framework/config`	Configuration
`@di-framework/auth`	Authentication
`@di-framework/authz`	Resource Authorization
`@di-framework/ai`	AI
`@di-framework/ai-utils`	Agent Skills — `SKILL.md`, `.agents/plugins`, jailed file tools, opt-in Bash
`@di-framework/bindings`	Native service bindings — PostgreSQL, key-value, blobstore, messaging, config, secrets, and outgoing HTTP
`@di-framework/cli-plugin-platform`	Platform — WASI 0.3 build, development, and deployment extension
`@di-framework/cli-plugin-ai`	AI CLI — `ai agent` and `ai skills`
`@di-framework/platform`	Shared Pulumi platform — infrastructure, tenant isolation, and Redis, NATS, blobstore, PostgreSQL, and egress backing services, tenant kubeconfigs, and the HTTP gateway used by kube and the platform CLI
`@di-framework/cloudfoundry`	Cloud Foundry — `VCAP_SERVICES` and `VCAP_APPLICATION` discovery
`@di-framework/cloudflare`	Cloudflare Workers — binding discovery, wrangler config, and DI injection

For a local Kubernetes platform and live service-binding examples, use the separate di-framework-kube CLI. It requires Node.js, npm, and Pulumi, and installs the shared platform package from npm. Its example workspace links DI Framework 6 with @di-framework/bindings and @di-framework/cli-plugin-platform for builds and di-framework platform deploy. Published applications use the same packages at @^6.

Next Steps

Now that you have the framework installed, learn how to use it:

Quick Start - Learn the basics with simple examples
CLI - Complete command tree, output contract, and package ownership
API Reference - Complete API documentation

Last modified: 03 November 2026