nextrush

The main NextRush package. One install, everything you need to start.

The Problem

Starting a new framework often means:

Decision paralysis — Which packages do I need?
Dependency hunting — Finding the right combination
Version mismatches — Getting compatible versions
Import confusion — Remembering which package exports what

You want to build an API, not manage dependencies.

Why This Package Exists

nextrush is a meta package that bundles the essential packages for Node.js development:

What You Get	From Package
`createApp()`, `Application`, `compose()`	`@nextrush/core`
`createRouter()`, `Router`	`@nextrush/router`
`listen()`, `serve()`, `createHandler()`	`@nextrush/adapter-node`
HTTP error classes and utilities	`@nextrush/errors`
TypeScript types, `HttpStatus`, `ContentType`	`@nextrush/types`
`VERSION`	`nextrush`

One install and one import path; defaults cover a typical Node.js API without extra config files.

Mental Model

Think of nextrush as the starter kit:

┌────────────────────────────────────────────────┐
│                   nextrush                      │
│                                                 │
│   ┌─────────┐  ┌─────────┐  ┌──────────────┐   │
│   │  core   │  │ router  │  │ adapter-node │   │
│   └─────────┘  └─────────┘  └──────────────┘   │
│                                                 │
│   ┌─────────┐  ┌─────────┐                     │
│   │ errors  │  │  types  │                     │
│   └─────────┘  └─────────┘                     │
└────────────────────────────────────────────────┘

It's not a monolith. Each package remains separate. The meta package re-exports them for convenience.

Installation

$ pnpm add nextrush

Quick Start

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

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

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

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

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

That's a complete API server. No additional installs needed.

The meta package targets Node.js. For Bun, Deno, or Edge runtimes, install packages individually with the appropriate adapter.

API Reference

Application

import { createApp, Application, compose } from 'nextrush';
import type { ApplicationOptions, ComposedMiddleware } from 'nextrush';

Export	Type	Description
`createApp`	Function	Creates an Application instance
`Application`	Class	The application class
`compose`	Function	Composes middleware array

Router

import { createRouter, Router } from 'nextrush';
import type { RouterOptions } from 'nextrush';

Export	Type	Description
`createRouter`	Function	Creates a Router instance
`Router`	Class	The router class

Server (Node.js)

import { listen, serve, createHandler } from 'nextrush';
import type { ServeOptions, ServerInstance } from 'nextrush';

Export	Type	Description
`listen`	Function	Start server on port (simple)
`serve`	Function	Start server with options
`createHandler`	Function	Create raw request handler

Errors

import {
  HttpError,
  NextRushError,
  BadRequestError,
  UnauthorizedError,
  ForbiddenError,
  NotFoundError,
  MethodNotAllowedError,
  ConflictError,
  UnprocessableEntityError,
  TooManyRequestsError,
  InternalServerError,
  NotImplementedError,
  BadGatewayError,
  ServiceUnavailableError,
  GatewayTimeoutError,
  createError,
  isHttpError,
  errorHandler,
  notFoundHandler,
  catchAsync,
} from 'nextrush';

import type { ErrorHandlerOptions, HttpErrorOptions } from 'nextrush';

Export	Status	Description
`HttpError`	Base	Base HTTP error class
`NextRushError`	Base	Base NextRush error class
`BadRequestError`	400	Invalid request
`UnauthorizedError`	401	Authentication required
`ForbiddenError`	403	Access denied
`NotFoundError`	404	Resource not found
`MethodNotAllowedError`	405	HTTP method not allowed
`ConflictError`	409	Resource conflict
`UnprocessableEntityError`	422	Validation failed
`TooManyRequestsError`	429	Rate limit exceeded
`InternalServerError`	500	Server error
`NotImplementedError`	501	Not implemented
`BadGatewayError`	502	Bad gateway
`ServiceUnavailableError`	503	Service unavailable
`GatewayTimeoutError`	504	Gateway timeout
`createError`	Factory	Create error by status code
`isHttpError`	Guard	Type guard for HTTP errors
`errorHandler`	Middleware	Error handling middleware
`notFoundHandler`	Middleware	404 fallback middleware
`catchAsync`	Deprecated	No-op — async errors propagate automatically

Types

import type {
  Context,
  Middleware,
  Next,
  Plugin,
  RouteHandler,
  HttpMethod,
  HttpStatusCode,
  Runtime,
} from 'nextrush';

import { HttpStatus, ContentType } from 'nextrush';

Constants

import { VERSION, HttpStatus, ContentType } from 'nextrush';

Export	Description
`VERSION`	Current NextRush version (`"3.0.0"`)
`HttpStatus`	HTTP status code constants
`ContentType`	Content type constants

Common Patterns

Basic REST API with CRUD operations

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

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

// In-memory store
const users = new Map<string, { id: string; name: string }>();

// List users
router.get('/users', (ctx) => {
  ctx.json([...users.values()]);
});

// Get user by ID
router.get('/users/:id', (ctx) => {
  const user = users.get(ctx.params.id);
  if (!user) throw new NotFoundError('User not found');
  ctx.json(user);
});

// Create user
router.post('/users', (ctx) => {
  const { name } = ctx.body as { name: string };
  const id = crypto.randomUUID();
  const user = { id, name };
  users.set(id, user);
  ctx.status = 201;
  ctx.json(user);
});

// Delete user
router.delete('/users/:id', (ctx) => {
  if (!users.delete(ctx.params.id)) {
    throw new NotFoundError('User not found');
  }
  ctx.status = 204;
  ctx.send(null);
});

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

With Error Handling

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

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

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

// Error handling
app.use(errorHandler());

// Routes
app.route('/', router);

// 404 fallback
app.use(notFoundHandler());

await listen(app, 3000);

With Middleware (Install Separately)

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

const app = createApp();

// Middleware stack
app.use(cors());
app.use(helmet());
app.use(json());

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

await listen(app, 3000);

What's NOT Included

The meta package is intentionally minimal. These require separate installation:

Feature	Package
CORS	`@nextrush/cors`
Security headers	`@nextrush/helmet`
Body parsing	`@nextrush/body-parser`
Rate limiting	`@nextrush/rate-limit`
Logging	`@nextrush/logger`
Static files	`@nextrush/static`
Decorators	`@nextrush/decorators`
Dependency injection	`@nextrush/di`
Controllers	`@nextrush/controllers`
Bun adapter	`@nextrush/adapter-bun`
Deno adapter	`@nextrush/adapter-deno`
Edge adapter	`@nextrush/adapter-edge`

This is intentional. Install only what you need.

When to Use This Package

✅ Use nextrush when:

Building Node.js APIs
Starting a new project
You want the simplest setup
You prefer importing from one place

❌ Don't use nextrush when:

Using Bun, Deno, or Edge runtimes
You need fine-grained control over dependencies
You're building a library that depends on NextRush

For Other Runtimes

If you're not on Node.js, install packages individually:

Bun

import { createApp } from '@nextrush/core';
import { createRouter } from '@nextrush/router';
import { serve } from '@nextrush/adapter-bun';

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

router.get('/', (ctx) => ctx.json({ runtime: 'bun' }));
app.route('/', router);

serve(app, { port: 3000 });

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

Deno

import { createApp } from '@nextrush/core';
import { createRouter } from '@nextrush/router';
import { serve } from '@nextrush/adapter-deno';

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

router.get('/', (ctx) => ctx.json({ runtime: 'deno' }));
app.route('/', router);

serve(app, { port: 3000 });

Package Details

Metric	Value
Dependencies	5 workspace packages
Node.js	≥22.0.0
TypeScript	Full support