Installation

Install NextRush with your package manager of choice, confirm the Node.js version requirement, and get a server running in one file.

Start here

Installing a web framework should take one command and a couple of minutes, not a checklist of peripheral tooling. NextRush ships as a single meta-package with everything the functional core needs, so the fastest path from an empty folder to a running server is genuinely short — you'll have one here before this page ends.

~5 minNode 22+TypeScriptNode · Bun · Deno · Edge

What you'll have

By the end of this page, three things are true and verified — not assumed:

✓ PackageInstallednextrush, via your package manager

✓ ServerRunningOne file, listening on :8080

✓ ResponseVerifiedA real request answered on localhost

Prerequisites

Runtime

Node.js 22.0.0 or newer

Package manager

pnpm, bun, npm, yarn, or deno

Editor

Any — full type definitions ship with every package

Download Node.js or manage versions with nvm. NextRush declares "engines": { "node": ">=22.0.0" } in every published package — this isn't a recommendation, it's what the framework is built and tested against. Examples on this page show all five package managers.

Why Node.js 22?

The framework targets ES2022 and stable ESM throughout — no CommonJS build exists for any @nextrush/* package. Node 22 is the oldest LTS line where that target lands cleanly, so it's the floor every adapter and example assumes. See the FAQ for the full reasoning.

Which path fits you?

Recommended

Two paths reach the same running server underneath — both install the same nextrush package; the scaffolder automates the folder and config around it. If you're unsure, scaffold — you can still read every file it produces afterward.

🚀 Scaffold a project

One command wires routing, middleware, scripts, and your chosen style (functional, class-based, or full).

⚙ Install manually

Add nextrush to an existing project, or wire each piece yourself to see how it fits together.

Install manually

Create a project folder

mkdir my-api && cd my-api
pnpm init

Add "type": "module" to the generated package.json. NextRush is ESM-only — there's no CommonJS build to fall back to — so Node needs to know your .ts/.js files are ES modules before anything else runs.

Expected result — the folder appears with a package.json containing "type": "module".

Install NextRush

$ pnpm add nextrush
$ pnpm add -D tsx typescript @types/node

Why it works:

nextrush is the meta-package — re-exports @nextrush/core, @nextrush/router, @nextrush/adapter-node, @nextrush/errors, and @nextrush/types in one install
This single install covers the functional path (createApp, createRouter, listen) with no separate packages to add
tsx runs the TypeScript entry file directly in the next step — no separate compile pass

Write a server and run it

Create src/index.ts:

src/index.ts

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

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

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

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

Run it:

npx tsx src/index.ts

Expected result — a JSON response on http://localhost:8080: {"status": "ok", "framework": "NextRush"}

Why it works:

createApp() builds the application
createRouter() gives you a router to attach routes to
app.route('/', router) mounts the router
listen(app, 8080) starts the Node adapter

If you see that JSON response, NextRush is installed and serving requests.

Configure TypeScript

NextRush ships full type definitions. This tsconfig.json matches what the framework's own examples and CI run against:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Only using class-based controllers?

Add "experimentalDecorators": true and "emitDecoratorMetadata": true to compilerOptions if you import from nextrush/class. That entry point auto-imports reflect-metadata itself — you don't add it to your own code or dependencies.

Installation complete — you have everything you need. Let's make sure it works.

Verify everything works

Two checks and you're done — runtime version, then the server responds.

Check 1 · Runtime

node --version
# → v22.x.x or newer

If node --version reports below 22, install a newer version before continuing — NextRush's adapters and examples aren't tested against older lines, and package installs may warn or fail depending on your package manager's engines enforcement.

Check 2 · Server

curl http://localhost:8080/
# → {"status":"ok","framework":"NextRush"}

🎉 Installation successful

Your request completed the full request path — the same one every NextRush app runs:

Application
Router
Handler
Response

createApp() built the application, the router matched / to your handler, and the handler wrote the response back through ctx.json(). Your environment is ready for a real application. Everything below this point is optional: pick it up whenever you need it.

Your next step

🚀 Build a Task API — recommended · ~20 min

The hands-on tutorial: routing, a JSON body, and a real 404 — starting from exactly where this page leaves off. Start the tutorial →

Other guides:

Scaffold with create-nextrush

Generate a project with your style, middleware, and runtime chosen up front.

Runtimes

Running on Bun, Deno, the edge, or serverless — the adapter each one needs.

Framework overview

The mental model — Application, Context, Router, and how they compose.

Now build something.

Optional: developer toolkit

🧰 @nextrush/dev

Most developers install this right after setup. Everything above ran without it — @nextrush/dev is a dev-only CLI, not a dependency your server needs — but it makes the loop from here on noticeably faster:

Hot-reload dev server (nextrush dev)
Production builds (nextrush build)
Code generators for controllers, services, middleware, guards, and routes

pnpm add -D @nextrush/dev

Optional. Install it only if you want a better day-to-day workflow — nothing on this page or the next tutorial requires it.

Dev server & builds

Hot reload while you develop, production builds with decorator metadata.

Code generators

Scaffold a controller, service, middleware, guard, or route from the command line.

When you're ready to deploy, see the production guide for runtime pinning, dependency trimming, and per-platform setup — that's a deployment concern, not an install one.

Having trouble?

Most installation issues fall into one of these three categories.

⚠ Server won't start; import errors on nextrush

Cause: package.json is missing "type": "module", so Node tries to load ESM output as CommonJS.

Fix: add "type": "module" — NextRush publishes no CommonJS build for any package to fall back to.

⚠ node --version is below 22

Cause: an older Node install or version manager default.

Fix: install/select Node 22 or newer before running pnpm add nextrush — the framework's engines field expects it everywhere.

⚠ Decorators throw reflect-metadata errors

Cause: importing nextrush/class without experimentalDecorators/emitDecoratorMetadata enabled in tsconfig.json.

Fix: add both compiler options — the reflect-metadata import itself is already handled for you.