Getting Started

This guide helps you choose the right packages and setup order for a new project. Express, Fastify, Next.js, and React Native all use the same entrypoints: @brushy/di/core on the server and @brushy/di/react on the client. See also: Migration v2 · Server · Best Practices

Quick rule

Pick your runtime (web, mobile, server, full stack).
Install the minimum package.
Add optional packages only if you need them (monitor, otel).

Which package to install first

Copy the command for your stack. Full stack / Next.js

npm install @brushy/di next react react-dom

React web

npm install @brushy/di react react-dom

Granular install (without umbrella):

npm install @brushy/di-core @brushy/di-react react react-dom

React Native

npm install @brushy/di react

Granular install:

npm install @brushy/di-core @brushy/di-react react

Express

npm install @brushy/di-core express

Fastify

npm install @brushy/di-core fastify

Script / worker / library (no React)

npm install @brushy/di-core

API + React frontend in the same project

npm install @brushy/di-core @brushy/di-react express react react-dom

Observability (optional)

npm install @brushy/di-monitor @brushy/di-otel

Published packages (v2)

Umbrella - core + react + monitor + otel

npm install @brushy/di

Core - Node, browser, RN without React hooks

npm install @brushy/di-core

React - web and React Native

npm install @brushy/di-react

Monitor

npm install @brushy/di-monitor

OpenTelemetry

npm install @brushy/di-otel

Imports (umbrella)

import { Container } from "@brushy/di/core";
import { useInject, BrushyDIProvider } from "@brushy/di/react";
import { monitor } from "@brushy/di/monitor";
import { traceContainer } from "@brushy/di/otel";

Imports by runtime

Express, Fastify, Nest, API routes

import { Container, createToken, server, runInRequestScope } from "@brushy/di/core";

app.use(server.brushyRequestScope());

Next.js Route Handlers / RSC

import { Container, runInRequestScopeAsync, server } from "@brushy/di/core";

React web, React Native, Next client

import { BrushyDIProvider, useInject } from "@brushy/di/react";

Full stack (umbrella)

import { Container, useInject, BrushyDIProvider } from "@brushy/di";

See Package entrypoints for the package split rationale.

Recipes by stack

React web

npm install @brushy/di react react-dom

// di/container.ts
import { Container, createToken } from "@brushy/di/core";

export const container = new Container();
export const USER_SERVICE = container.register(createToken<UserService>("USER_SERVICE"), {
  useClass: UserService,
  lifecycle: "singleton",
});

// app/providers.tsx
"use client";
import { BrushyDIProvider } from "@brushy/di/react";
import { container } from "./di/container";

export function AppProviders({ children }: { children: React.ReactNode }) {
  return <BrushyDIProvider container={container}>{children}</BrushyDIProvider>;
}

// components/profile.tsx
import { useInject } from "@brushy/di/react";
import { USER_SERVICE } from "../di/container";

export function Profile() {
  const users = useInject(USER_SERVICE);
  // ...
}

Next: React Hooks

React Native

Same install and provider pattern as web. Metro resolves the react-native field automatically.

npm install @brushy/di react

import { BrushyDIProvider, useInject } from "@brushy/di/react";
import { Container, createToken } from "@brushy/di/core";

Important: In dev, useInjectComponent shows a default error UI with DOM elements on web. On React Native, register a platform renderer once at bootstrap (otherwise UI is null and errors still log to console.error):

import { Text, View } from "react-native";
import { setInjectComponentErrorRenderer } from "@brushy/di/react";

setInjectComponentErrorRenderer((message, details) => (
  <View>
    <Text>{message}</Text>
    {details ? <Text>{details}</Text> : null}
  </View>
));

Next: Component Injection

Express

npm install @brushy/di-core express

import express from "express";
import { Container, createToken, server } from "@brushy/di/core";

const USER_SERVICE = createToken<UserService>("USER_SERVICE");
const container = new Container();
container.register(USER_SERVICE, { useClass: UserService, lifecycle: "scoped" });

server.setServerContainer(container);

const app = express();
app.use(server.brushyRequestScope());

app.get("/users", (_req, res) => {
  const users = server.resolve(USER_SERVICE);
  res.json(users.list());
});

app.listen(3000);

Next: Server Utilities

Fastify

Fastify is not Connect-compatible. Wrap each request with runInRequestScope:

npm install @brushy/di-core fastify

import Fastify from "fastify";
import { Container, createToken, runInRequestScope } from "@brushy/di/core";

const USER_SERVICE = createToken<UserService>("USER_SERVICE");
const container = new Container();
container.register(USER_SERVICE, { useClass: UserService, lifecycle: "scoped" });

const app = Fastify();

app.addHook("onRequest", async (_req, _reply) => {
  // Scope is entered per route handler below
});

app.get("/users", async (_req, reply) => {
  const users = runInRequestScope(
    () => container.resolve(USER_SERVICE),
    { container },
  );
  return reply.send(users.list());
});

For production, prefer runInRequestScopeAsync in async handlers. Full patterns: Server Utilities.

Next.js (App Router)

npm install @brushy/di next react react-dom

Client Components

import { BrushyDIProvider, useInject } from "@brushy/di/react";

Route Handlers / server

import { Container, runInRequestScopeAsync, server } from "@brushy/di/core";

React Server Components

import { Container, createToken } from "@brushy/di/core";
// resolve on the server - no React hooks

// lib/di-setup.ts - module singleton (initialize once)
import { Container, createToken, server } from "@brushy/di/core";

let initialized = false;
export const USER_REPO = createToken<UserRepository>("USER_REPO");

export function setupServerContainer() {
  if (initialized) return;
  const container = new Container();
  container.register(USER_REPO, { useClass: UserRepository, lifecycle: "scoped" });
  server.setServerContainer(container);
  initialized = true;
}

// app/api/users/route.ts
import { NextResponse } from "next/server";
import { runInRequestScopeAsync, server } from "@brushy/di/core";
import { setupServerContainer, USER_REPO } from "@/lib/di-setup";

export async function GET() {
  setupServerContainer();
  const users = await runInRequestScopeAsync(
    () => server.resolve(USER_REPO).findAll(),
    { container: server.getServerContainer() },
  );
  return NextResponse.json(users);
}

// app/providers.tsx
"use client";
import { BrushyDIProvider } from "@brushy/di/react";
import { clientContainer } from "@/lib/client-container";

export function Providers({ children }: { children: React.ReactNode }) {
  return <BrushyDIProvider container={clientContainer}>{children}</BrushyDIProvider>;
}

Do not rely on Next.js Edge middleware for Node ALS request scope in Route Handlers - bind scope inside the handler with runInRequestScopeAsync. Next: Server - Next.js App Router example

Backend-only (no React)

npm install @brushy/di-core

import { Container, createToken, resolve } from "@brushy/di/core";

const LOGGER = createToken<Logger>("LOGGER");
const container = new Container();
container.register(LOGGER, { useClass: Logger, lifecycle: "singleton" });

const logger = container.resolve(LOGGER);
logger.info("ready");

Optional add-ons

Install only when needed:

npm install @brushy/di-monitor   # runtime metrics / logging hooks
npm install @brushy/di-otel      # OpenTelemetry tracing

Next steps

Container - registration and lifecycles
Server - request scope, Express, Next.js
Best Practices - tokens, scopes, testing
Migration v2 - package split and imports

Introduction

@brushy/di-core

Guides

@brushy/di-monitor

React

Migration

Quick rule

Which package to install first

Published packages (v2)

Imports (umbrella)

Imports by runtime

Recipes by stack

React web

React Native

Express

Fastify

Next.js (App Router)

Backend-only (no React)

Optional add-ons

Next steps

​Quick rule

​Which package to install first

​Published packages (v2)

​Imports (umbrella)

​Imports by runtime

​Recipes by stack

​React web

​React Native

​Express

​Fastify

​Next.js (App Router)

​Backend-only (no React)

​Optional add-ons

​Next steps

Quick rule

Which package to install first

Published packages (v2)

Imports (umbrella)

Imports by runtime

Recipes by stack

React web

React Native

Express

Fastify

Next.js (App Router)

Backend-only (no React)

Optional add-ons

Next steps