Installation

Prerequisites, scaffold with create-nextrush, or install the nextrush meta-package by hand

NextRush requires Node.js 22 or later. For Bun or Deno, add the matching adapter package (the scaffolder can do this when you pick a runtime).

Prerequisites

Before installing NextRush, ensure you have:

Node.js 22+ — Download or use a version manager like nvm
A package manager — pnpm (recommended), npm, yarn, or bun

Why Node.js 22?

The framework targets ES2022, stable ESM, and APIs the docs assume are available on the supported Node line. Use 22.x or newer so pnpm create nextrush, tsx, and the Node adapter match what CI and examples run against.

Choose your setup path

Pick one path and stay on it until you have a running server:

Scaffold a project

Scaffold a ready-to-run app with runtime, middleware, and style presets.

Install manually

Pick packages yourself when you want to wire each layer explicitly.

Scaffold a project

If you want a working app immediately, use create-nextrush.

# Interactive (space between "create" and "nextrush" is intentional)
pnpm create nextrush
npm create nextrush

# Pin the scaffolder version
npm create nextrush@latest

# Same package via its npm name (hyphen)
pnpm dlx create-nextrush@latest

# non-interactive example
pnpm create nextrush my-api --style functional --middleware api --runtime node

The scaffolder generates a ready-to-run project with routing, middleware, scripts, and optional controllers + DI support. For every supported command (npm create, npx, pnpm dlx), flags, and templates, see create-nextrush.

What the scaffold asks

Project name, style (functional, class-based, or full), middleware preset, runtime target, package manager, dependency install, and git init.

Install manually

Create a project folder

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

Add "type": "module" to package.json so Node treats .js output as ESM (the scaffolder does this for you).

Install NextRush

Choose your preferred package manager:

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

The nextrush package is a meta-package that includes the essentials plus the nextrush CLI (via @nextrush/dev) so you can run npx nextrush dev and npx nextrush build after installing it:

@nextrush/core — Application and middleware
@nextrush/router — HTTP routing
@nextrush/adapter-node — Node.js HTTP server adapter
@nextrush/errors — HTTP error classes
@nextrush/types — Shared TypeScript types
@nextrush/dev — Development server, production build, generators (transitive dependency)

Verify Installation

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, 3000);

Run it:

npx tsx src/index.ts

Open http://localhost:3000 in your browser. You should see:

{ "status": "ok", "framework": "NextRush" }

Configure TypeScript

NextRush is written in TypeScript and provides full type definitions. For accurate types and decorator metadata, use these tsconfig.json settings:

tsconfig.json

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

Decorators and DI

If you use class-based controllers with @nextrush/di, add "experimentalDecorators": true and "emitDecoratorMetadata": true to your compilerOptions. The nextrush meta-package auto-imports reflect-metadata — no manual setup needed.

Set Up Project Structure

A typical NextRush project looks like this:

my-api/
├── src/
│   ├── index.ts          # Application entry point
│   ├── routes/           # Route handlers
│   │   ├── users.ts
│   │   └── products.ts
│   └── middleware/       # Custom middleware
│       └── auth.ts
├── package.json
└── tsconfig.json

No Prescribed Structure

NextRush does not enforce a specific project structure. Organize your code in whatever way makes sense for your team.

Individual Packages

For more control, install packages individually:

$ pnpm add @nextrush/core @nextrush/router @nextrush/adapter-node

This is useful when:

You want to minimize bundle size
You're using a different runtime adapter (Bun, Deno, Edge)
You need fine-grained control over versions

Optional packages reference

Middleware

$ pnpm add @nextrush/cors @nextrush/helmet @nextrush/body-parser

Plugins

$ pnpm add @nextrush/controllers @nextrush/logger @nextrush/static

Runtime Adapters

$ pnpm add @nextrush/adapter-bun @nextrush/adapter-deno @nextrush/adapter-edge

Development Tools

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

@nextrush/dev — nextrush dev, nextrush build, and nextrush generate when you assemble packages individually (the nextrush meta-package also pulls this in; see scaffold or manual meta install)
tsx — Run TypeScript directly without compilation
typescript — TypeScript compiler
@types/node — Node.js type definitions

Next Steps

If you installed by hand, continue to Quick start for a longer manual tour (routing, middleware, JSON bodies).

If you used the scaffold, open the generated src/index.ts and run the dev script from the project package.json (for example pnpm dev). For CLI flags and templates, see create-nextrush.

Scaffold a project

Install manually

On this page