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/socket`	Sockets
`@di-framework/rpc`	RPC
`@di-framework/config`	Configuration
`@di-framework/auth`	Authentication
`@di-framework/authz`	Resource Authorization
`@di-framework/ai`	AI

Next Steps

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

Quick Start - Learn the basics with simple examples
CLI - App init/check/build and maintainer mx
API Reference - Complete API documentation

Last modified: 09 August 2026