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:

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

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!

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/repo`	Repositories
`@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/wasmcloud`	Native service bindings — PostgreSQL, key-value, blobstore, messaging, config, secrets, and outgoing HTTP
`@di-framework/cli-plugin-wasmcloud`	wasmCloud — WASI 0.3 build, development, and deployment extension
`@di-framework/platform`	Shared Pulumi platform — infrastructure, tenant isolation, and Redis/NATS backing services used by kube and the wasmCloud extension

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. The example workspace pins the framework packages and wasmCloud extension to 5.3.0.

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: 15 September 2026