Package Hierarchy

NextRush uses a modular monorepo architecture. Each package has a single responsibility and explicit dependencies.

This page has two diagrams: "The Big Picture" below is a curated, hand-arranged diagram grouped by architectural layer (Foundation, Core, Adapters, …) for readability. The Dependency Graph (Generated from Source) further down is mechanically produced from every package's real package.json — see the callout there for how, and trust it first if the two ever disagree.

The Big Picture

Package Categories

Foundation Layer

These packages form the base of the hierarchy. They depend only on each other — never on higher layers.

import type { Context, Middleware, Extension } from '@nextrush/types';
import { NotFoundError, BadRequestError } from '@nextrush/errors';
import { getRuntime, getRuntimeCapabilities } from '@nextrush/runtime';

Core Layer

The essential packages that make up the framework:

import { createApp, compose } from '@nextrush/core';
import { createRouter } from '@nextrush/router';
import { Service, Repository, container } from '@nextrush/di';

Adapter Layer

Platform-specific HTTP handling:

import { listen } from '@nextrush/adapter-node';
import { serve } from '@nextrush/adapter-bun';
import { createHandler } from '@nextrush/adapter-edge';

Middleware Layer

Reusable middleware packages. All middleware depends only on @nextrush/types.

import { json, urlencoded } from '@nextrush/body-parser';
import { cors } from '@nextrush/cors';
import { helmet } from '@nextrush/helmet';
import { compression } from '@nextrush/compression';
import { rateLimit } from '@nextrush/rate-limit';
import { validate } from '@nextrush/validation';

Class Runtime, Extensions & Registrars Layer

@nextrush/class is the unified class-based API — it consolidates the former @nextrush/decorators and @nextrush/controllers split (both packages have been removed — see Deprecations), and re-exports @nextrush/di. Beyond that, the remaining extensions layer is mostly middleware, plus one registrar and one Extension:

import { registerControllers, registerModule } from 'nextrush/class';
import { logger } from '@nextrush/logger';
import { serveStatic } from '@nextrush/static';

Dev Tools

Meta Package

Convenience package that re-exports essentials:

import { createApp, createRouter, listen } from 'nextrush';

nextrush/class is a separate subpath export of the same meta package — it re-exports @nextrush/class's full surface (decorators, DI, modules, guards, interceptors, filters, lifecycle) without pulling those symbols into the root nextrush import.

Dependency Rules

NextRush follows strict dependency rules: lower packages never import from higher packages, and circular dependencies are blocked at CI. If you encounter an import error, check the hierarchy diagram above.

1. types is the root — no internal dependencies

@nextrush/types → (none)

2. Foundation packages depend only on types

@nextrush/errors → types
@nextrush/runtime → types, errors

3. Core packages depend on foundation

@nextrush/core → types, errors
@nextrush/router → types
@nextrush/di → reflect-metadata, tsyringe

4. Adapters depend on core + runtime + foundation

@nextrush/adapter-node → core, runtime, errors, types
@nextrush/adapter-bun → core, runtime, errors, types

5. Middleware depends only on types

@nextrush/cors → types
@nextrush/body-parser → types

6. The class runtime depends on di + foundation + core/router

@nextrush/class → di, errors, router, types, core

Dependency Graph (Generated from Source)

The script scanned 36 package.json files under packages/ (35 publishable packages plus the private, never-published @nextrush/adapter-conformance test suite — see Versioning & Compatibility) and found 67 internal @nextrush/* edges (external dependencies like tsyringe and reflect-metadata are listed per-package below the graph, not as graph nodes — the graph's job is the internal hierarchy).

Findings from the generated scan (not visible in the curated diagram above)

Running the script surfaced two facts worth stating plainly rather than folding into the curated diagram, since a hand-arranged diagram can hide exactly this kind of detail:

• @nextrush/logger depends on @nextrush/log (^0.2.1) — a separately published external package, not a workspace member. It is the one genuine external-runtime-dependency case outside the three named exceptions in Design Principles (reflect-metadata, tsyringe, @clack/prompts). Verified directly against packages/middleware/logger/package.json — this is not a typo in the graph script, @nextrush/log really is declared as a runtime dependency there.
• nextrush (the meta package) no longer depends on @nextrush/decorators or @nextrush/controllers — both were removed from its dependencies when the two shim packages were deleted from the workspace (see Deprecations). It depends only on @nextrush/class for the class-based API surface now.

Package Size Targets

Each package has a maximum size to keep the framework lean:

@nextrush/class has no fixed LOC ceiling in the current targets — it consolidates what were previously three separately-budgeted packages (decorators, di re-export, controllers).

Common Installation Patterns

Choose the pattern that matches your project needs.

npm install @nextrush/core @nextrush/router @nextrush/adapter-node

import { createApp } from '@nextrush/core';
import { createRouter } from '@nextrush/router';
import { listen } from '@nextrush/adapter-node';

const app = createApp();
const router = createRouter();

router.get('/', (ctx) => ctx.json({ hello: 'world' }));
app.route('/', router);
await listen(app, 8080);

npm install nextrush

import { createApp, createRouter, listen } from 'nextrush';

const app = createApp();
const router = createRouter();

router.get('/', (ctx) => ctx.json({ hello: 'world' }));
app.route('/', router);
await listen(app, 8080);

npm install nextrush @nextrush/cors @nextrush/helmet @nextrush/body-parser @nextrush/rate-limit

import { createApp, createRouter, listen } from 'nextrush';
import { cors } from '@nextrush/cors';
import { helmet } from '@nextrush/helmet';
import { json } from '@nextrush/body-parser';
import { rateLimit } from '@nextrush/rate-limit';

const app = createApp();
app.use(cors());
app.use(helmet());
app.use(json());
app.use(rateLimit({ window: '1m', max: 100 }));

const router = createRouter();
router.get('/', (ctx) => ctx.json({ hello: 'world' }));
app.route('/', router);

await listen(app, 8080);

npm install nextrush

import { createApp, listen } from 'nextrush';
import { Controller, Get, Service, registerControllers } from 'nextrush/class';

@Service()
class GreetingService {
  greet() {
    return { hello: 'world' };
  }
}

@Controller('/')
class HomeController {
  constructor(private greeting: GreetingService) {}

  @Get()
  index() {
    return this.greeting.greet();
  }
}

const app = createApp();
await registerControllers(app, {
  root: './src',
  prefix: '/api',
});
await listen(app, 8080);

Explore Packages