Framework Overview

Pick a path

Prerequisites

For editor and tooling (lint, format), see Installation.

What this page covers

This is the broadest getting-started doc: runnable hello world, feature highlights, request lifecycle, concept links, package diagram, both programming styles, performance and runtime tables, and migration hints. Use the list below to jump to a section.

Errors, testing, and deployment

Production APIs need clear failures and checks — not only routing:

• HTTP errors — HttpError hierarchy and handlers: Errors (API) · Error handling (guide)
• Tests — Vitest patterns for apps and middleware: Testing
• Ship — build, env, hosting: Deployment

Hello World in under a minute

$ pnpm add nextrush

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

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

router.get('/', (ctx) => ctx.json({ message: 'Hello NextRush' }));

app.route('/', router);
await listen(app, 3000);
// → http://localhost:3000

Why NextRush

How a request flows

Every HTTP request follows the same path:

1. Adapter receives the raw request and builds a Context
2. Application runs the middleware pipeline
3. Router matches the URL and extracts params
4. Handler runs your logic and sets the response
5. Response unwinds through middleware
6. Adapter sends bytes to the client

Core concepts

Eight ideas cover most of the framework. Each has a dedicated concept page.

Application

The container for middleware, plugins, routes, and errors.

import { createApp } from 'nextrush';

const app = createApp();

Application →

Context

One object per request for input, output, and shared state.

router.get('/users/:id', (ctx) => {
  const { id } = ctx.params;
  const { page } = ctx.query;
  const auth = ctx.get('authorization');

  ctx.status = 200;
  ctx.json({ id, page, auth });
});

Context →

Middleware

Onion-style pipeline — code before ctx.next() runs inbound; code after runs outbound.

app.use(async (ctx) => {
  const start = Date.now();
  await ctx.next();
  ctx.set('X-Response-Time', `${Date.now() - start}ms`);
});

Middleware →

Routing

Segment trie with O(d) depth lookup; static routes use fast paths. Params, wildcards, and nested routers supported.

import { createRouter } from 'nextrush';

const users = createRouter();

users.get('/', (ctx) => ctx.json([]));
users.get('/:id', (ctx) => ctx.json({ id: ctx.params.id }));
users.post('/', (ctx) => ctx.json(ctx.body, 201));

app.route('/users', users);

Routing →

Plugins

Extend the app at startup: register middleware, routes, or lifecycle hooks without forking core.

import { controllersPlugin } from '@nextrush/controllers';
import { eventsPlugin } from '@nextrush/events';

app.plugin(eventsPlugin());
app.plugin(controllersPlugin({ router, root: './src' }));

Plugins →

Guards

Route-level access checks. Return false → 403 before the handler runs.

import type { GuardFn } from '@nextrush/decorators';

const AuthGuard: GuardFn = (ctx) => {
  return Boolean(ctx.get('authorization'));
};

@UseGuard(AuthGuard)
@Controller('/admin')
class AdminController {
  @Get('/dashboard')
  dashboard() {
    return { admin: true };
  }
}

Guards →

Dependency injection

Register services (singleton or transient) and inject into controllers.

import { Service } from '@nextrush/di';

@Service()
class UserService {
  async findAll() {
    return [{ id: 1, name: 'Alice' }];
  }
}

@Controller('/users')
class UserController {
  constructor(private users: UserService) {}

  @Get()
  findAll() {
    return this.users.findAll();
  }
}

Adapters

Runtime-specific HTTP I/O. Your app code stays the same.

import { listen } from 'nextrush'; // Node.js (default)
// import { listen } from '@nextrush/adapter-bun';
// import { listen } from '@nextrush/adapter-deno';
// import { listen } from '@nextrush/adapter-edge';

await listen(app, 3000);

Package architecture

30 packages in the monorepo. Lower layers never import from higher layers:

Package hierarchy →

Two programming styles

Use functions for small services; add controllers and DI when the API grows. Both styles can coexist.

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

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

app.use(cors());
app.use(json());

router.get('/users', (ctx) => {
  ctx.json([{ id: 1, name: 'Alice' }]);
});

router.post('/users', (ctx) => {
  ctx.json(ctx.body, 201);
});

router.get('/users/:id', (ctx) => {
  ctx.json({ id: ctx.params.id });
});

app.route('/api', router);
await listen(app, 3000);

import { createApp, createRouter, listen } from 'nextrush';
import { controllersPlugin, Controller, Get, Post, Body, Service } from 'nextrush/class';

@Service()
class UserService {
  private users = [{ id: 1, name: 'Alice' }];

  findAll() {
    return this.users;
  }

  create(data: { name: string }) {
    const user = { id: this.users.length + 1, ...data };
    this.users.push(user);
    return user;
  }
}

@Controller('/users')
class UserController {
  constructor(private userService: UserService) {}

  @Get()
  findAll() {
    return this.userService.findAll();
  }

  @Post()
  create(@Body() data: { name: string }) {
    return this.userService.create(data);
  }
}

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

await app.plugin(controllersPlugin({ router, root: './src', prefix: '/api' }));
app.route('/', router);

await listen(app, 3000);

Design constraints

Segment trie routing, pre-compiled middleware composition, and avoiding extra allocations on the request path keep overhead low. Cold-start and idle memory depend on process and OS — measure in your environment if those drive your product.

Full benchmarks →

Runtime support

The nextrush package ships the Node adapter. Install other adapters when you target Bun, Deno, or Edge.

Coming from another stack?

Express

• Middleware: (req, res, next) vs one ctx and ctx.next()
• Routing: linear scan vs segment trie (O(depth))
• Types: @types/express vs first-party strict types

Fastify

• Plugins: Fastify encapsulation vs flat NextRush plugin() installs
• Validation: JSON Schema vs transforms (Zod, Valibot, …)
• Decorators: add-on only vs @Controller / @Get with DI when you want them

What ships in nextrush

Optional layers:

Next steps

Community

• Repository — github.com/0xTanzim/nextrush
• Discussions — GitHub Discussions
• Agent skills — Skills directory for AI-assisted development