NextRush in One Page

The one line every request walks — the recurring motif you'll see broken down below:

1. Request
3. Application
5. Middleware
7. Router
9. Handler
11. Response

Five acts, in order — Why it exists, How it works, what you'd spend most of your time on Building, where it ends up Running, and Learning where to go next:

1. Why
3. How
5. Building
7. Running
9. Learning

Act 1 · Why

Before any piece of the framework, the reasoning behind all of them: what building an API without NextRush actually feels like, and the four commitments NextRush makes instead.

Why NextRush exists

Picture the last time you started a plain Express API. Routes are wired by hand, request bodies come in untyped until you add and configure a parser, and nothing stops a req.user from being undefined at 2am in production. Reach for Fastify and the throughput problem is solved, but you're Node-only and writing JSON-Schema by hand for every route. Reach for NestJS and the structure problem is solved, but now you're learning decorators, modules, and an Angular-shaped runtime before your first GET even exists.

Every one of those frameworks is good at what it optimizes for. The problem is that each one asks you to accept a real cost to get there — an ecosystem you wire by hand, a runtime you're locked into, or a framework you have to learn before you can use it. NextRush is what happens when none of those costs are treated as the price of entry. Strict types from the first route, structure that's optional instead of mandatory, a core small enough to read start to finish in one sitting, and the same application code running on four different runtimes.

That's the shape of the bet this framework makes. The head-to-head comparison against Express, Fastify, Koa, NestJS, and Hono lives on the Introduction; the rest of this page is about how NextRush itself thinks once you're inside it.

The philosophy

Four commitments explain nearly every design decision in the framework. Hold these and the rest follows:

Act 2 · How

The philosophy explains why. This act shows how — one request, traced through every piece it touches, starting with the single diagram the rest of the page keeps pointing back to.

The framework on one diagram

This is the picture to redraw from memory. Every chapter after it explains one node on it. A request enters the Application, flows down the Middleware pipeline, the Router picks a handler — written either as a plain function or as a class controller — and both read from and write to the same Context before a Response goes back out.

The two handler shapes converge on one Context and one Response — that convergence is the point: functional and class are two ways to write the same pipeline, not two frameworks.

Application

A request arrives at one place first — the Application owns that place. Every later node on the flow (Application → Middleware → Router → Context) is something it holds or hands the request down to.

Why a separate piece at all? Because something has to own the pipeline before any request logic runs — a place to register middleware and mount routers once, instead of re-wiring them on every request. That's all the Application is: the entry point and orchestrator. It doesn't match routes or handle requests itself — it owns the pieces that do and hands each request down the chain.

Run this and it answers a request — nothing else has been added yet:

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

const app = createApp(); // owns the chain; nothing runs until you add to it
const router = createRouter();

router.get('/', (ctx) => ctx.json({ status: 'ok' }));

app.route('/', router);
await listen(app, 8080); // curl localhost:8080/ → {"status":"ok"}

Full detail: Application.

Middleware

The Application owns the pipeline; the pipeline still needs behavior that runs for every request regardless of path — that behavior goes in Middleware, the second node on the flow.

Why not put auth and logging straight in the handler? Because then every handler re-implements them, and a change to how you log means editing every route. Middleware wraps that behavior around a handler like layers of an onion — one place for auth, body parsing, and logging — instead of one copy per route. Each layer runs before the handler, calls ctx.next(), and then runs again after on the way back out. The rule that trips people up: order of registration is order of execution.

A middleware you can register right now — timing every request:

app.use(async (ctx) => {
  const start = Date.now();
  await ctx.next(); // before this line: on the way in. after it: on the way out.
  console.log(`${ctx.method} ${ctx.path} — ${Date.now() - start}ms`);
});

Full detail: Middleware.

Router

Middleware ran for every request; the next job is to pick the ONE handler responsible for this path — that's the Router's job, the third node on the flow and where the pipeline hands off to your code.

Why not check the URL yourself in one big handler? Because that turns into an unmaintainable chain of if statements the moment you have more than a few routes. The Router maps a request's path to the one handler responsible for it. It's backed by a segment trie, so lookup cost tracks how many segments a URL has, not how many routes you've registered. It captures parameters (/users/:id) and supports grouping and mounting sub-routers under a prefix.

That tree is the structure a request walks segment by segment. Here it is as real routes:

const router = createRouter();

router.get('/users/:id', (ctx) => ctx.json({ id: ctx.params.id }));
router.get('/tasks/:id', (ctx) => ctx.json({ id: ctx.params.id }));
// GET /users/42 → { "id": "42" } — :id is captured as a string

Full detail: Router.

Context

Application, Middleware, and the Router's handler all need to read the same per-request shape and write back to the same response — that's the fourth and final concept node, Context.

Why one object instead of the raw request and response? Because juggling req and res separately means remembering two APIs, two mutation points, and — across runtimes — two different underlying types. Context (ctx) is the one per-request object every step reads from and writes to instead. You never touch the raw req/res directly — ctx carries the request in and the response out, and it's fresh per request so nothing leaks between concurrent ones.

router.post('/tasks', (ctx) => {
  const body = ctx.body as { title: string }; // in: parsed by a body-parser middleware
  ctx.status = 201; // out: status
  ctx.json({ id: 1, title: body.title }); // out: JSON response
});

Full detail: Context.

Act 3 · Building

You now know how one request flows. This act is about writing the code that handles it: what you install, which syntax you write it in, and how to add capability beyond a single request.

Packages

Why does this come before you've even written a route? Because it's one of NextRush's core differences from a batteries-included framework, and it shapes every decision after this point: you never install more than the request you're building actually needs. The nextrush meta-package gives you the core — createApp, createRouter, listen, the Context API, and the error classes. It does not bundle validation, CORS, security headers, or WebSocket support. You add each capability as its own package, so your install stays as small as your app.

import { createApp, listen } from 'nextrush';
import { cors } from '@nextrush/cors'; // added because this API is called cross-origin
import { json } from '@nextrush/body-parser'; // added because a route reads a JSON body

const app = createApp();
app.use(cors());
app.use(json());
await listen(app, 8080);

Decide what to install by what the request needs, not by habit:

Full detail: packages reference.

Two programming styles

Why does the framework support two ways to write the same thing? Because "small service" and "large team" want different amounts of structure, and forcing one style onto both means either over-engineering the small service or under-structuring the large one. NextRush gives you two ways to write the same pipeline, and you can mix them in one project. Both compile to identical routing and middleware — same engine, different syntax, no performance trade-off.

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

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

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

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

import { Controller, Get, Param } from 'nextrush/class';

@Controller('/users')
class UserController {
  @Get('/:id')
  findOne(@Param('id') id: string) {
    return { id };
  }
}

Full detail: Application (functional) and dependency injection (class-based).

Extensions

You've seen Middleware, Routes, and Context — all per-request. Some capabilities don't run per request at all (a DB pool, an event bus) and live for the app's whole lifetime instead.

Why isn't everything middleware, if middleware handles 99% of capability? Because some things aren't per-request at all — a database connection pool or an event bus needs to boot once and live for the app's lifetime, not run on every request. NextRush gives you three mechanisms, and which one you reach for is a decision, not a guess:

import { events } from '@nextrush/events';

const app = createApp().extend(events()); // boots once, lives for the app's lifetime
await app.ready();

This is capability composition in practice: the base stays small, and you add exactly the mechanism a feature needs. Full detail: Extensions.

Errors

Everything so far assumed a handler finished normally. Errors are the escape hatch — what runs when one cannot.

Why throw instead of returning an error object? Because a thrown error can't be silently ignored the way a returned value can — forgetting to check a return value is a real, common bug; forgetting to catch a throw is not, since the framework catches it for you either way. You throw a typed error class, and the framework maps it to the right status and JSON body. You describe what went wrong, not how to format it — and internal stack traces never leak in production.

import { NotFoundError } from 'nextrush';

router.get('/tasks/:id', (ctx) => {
  const task = tasks.get(Number(ctx.params.id));
  if (!task) throw new NotFoundError('Task not found'); // → 404, formatted for you
  ctx.json(task);
});

Act 4 · Running

You've built something. This act is about where it actually runs — the runtimes NextRush targets, the seam that makes that possible, and what the server does across its whole lifetime, not only one request.

One app, every runtime

Why should switching runtimes cost this little? Because the request path speaks only web-standard Request/Response, so your application code — routes, middleware, controllers — doesn't change when you move it. Only the entry adapter does.

Full detail: runtime compatibility.

Adapters

Why doesn't the framework target Node only and call it done? Because the moment it hard-codes Node's APIs anywhere in the request path, "one app, every runtime" stops being true. An adapter is the bridge between your application and a runtime's native server — the same app from every chapter above, unchanged, handed to a different listen-equivalent per runtime.

// The same app — only the adapter import changes per runtime
import { createApp, createRouter } from 'nextrush';
import { listen } from '@nextrush/adapter-node'; // swap for @nextrush/adapter-bun, etc.

const app = createApp();
// ...routes, middleware — identical on every runtime
await listen(app, 8080);

That single adapter seam — the only layer that changes — is what makes "one app, every runtime" true rather than aspirational. The runtime target is any of the five above (Node, Bun, Deno, Edge, or Serverless).

The request lifecycle

Why look at the whole server instead of one request? Because a request handled correctly can still be dropped if the server exits mid-response — correctness at the request level isn't enough without correctness at the process level too. The Application starts, becomes ready, handles requests, and — on a shutdown signal — drains in-flight work before exiting. Readiness and draining are what let it deploy behind an orchestrator without dropping requests.

import { createApp } from 'nextrush';
import { serve } from '@nextrush/adapter-node';

const app = createApp();
await serve(app, { port: 8080, gracefulShutdown: true }); // drains on SIGTERM/SIGINT before exiting

Full detail: request lifecycle.

Act 5 · Learning

You have the map. This last act is about what it's actually for — the services it's built to produce, and exactly where to go to turn this understanding into a running application.

What you can build

The pieces above combine into real services. A few shapes NextRush is built for:

Your learning path

You have the map. Here's the order the rest of the docs are meant to be read in — each stage assumes the one before it:

One last picture before you go

You started with this line:

1. Request
3. Application
5. Middleware
7. Router
9. Handler
11. Response

That's the whole framework. Everything in the five acts above is one node on it, one runtime for it, or one detail about how it's wired. Read the code and you know what happens on every request — no hidden middleware, no auto-wired magic, no runtime you didn't ask for. Start with the Task API tutorial to make that line true for your first app, then keep this diagram in mind as a map the rest of the docs fill in.