FAQ

Common questions about NextRush, answered directly.

Getting started with NextRush

What is NextRush?

A modular backend framework for Node.js, Bun, Deno, and Edge runtimes. Under 3,000 lines of code, zero runtime dependencies, full TypeScript strict mode. It gives you functional routes for quick prototypes and class-based controllers with DI when your project grows.

Can I use NextRush in production?

Yes. NextRush v3 ships as semver-stable releases on npm (core packages at 3.1.0 today): breaking changes bump the major version per Semantic Versioning. Follow release notes and upgrade guides when upgrading major versions. For regulated environments, run your usual QA and staging gates before rollout.

What Node.js version does NextRush require?

Node.js 22.0.0 or higher. NextRush uses modern JavaScript features (ESM, top-level await, native fetch) that require recent Node.js versions.

Why another Node.js framework?

Different stacks optimize for different defaults: Express stays minimal, NestJS leans on structure and modules, Fastify targets Node.js throughput. NextRush keeps a small core and optional decorators/DI, ships several runtime adapters, and avoids extra runtime dependencies in core packages.

Architecture

Why zero dependencies?

External dependencies are the largest source of supply chain vulnerabilities and breaking changes. By implementing everything internally, NextRush controls its entire surface area. The only runtime dependencies across the core/adapter/middleware line are reflect-metadata (required for decorator-based DI) and, inside @nextrush/di, tsyringe (the DI container it wraps). See Package Hierarchy for the full dependency chain.

Why both functional and class-based styles?

Different projects need different levels of structure. A 50-line microservice doesn't need decorators and DI. A large API with 200+ endpoints benefits from controllers, dependency injection, and guards. NextRush lets you start functional and adopt class-based patterns incrementally — both styles work together in the same application.

How does the package hierarchy work?

NextRush is 35 publishable packages in the monorepo, organized in a strict dependency chain:

types → errors → core → router → runtime → di → class → adapters → middleware

(@nextrush/class consolidates the former @nextrush/decorators + @nextrush/controllers split and re-exports @nextrush/di; both older packages have been removed after serving briefly as deprecated compatibility shims.) Lower packages never import from higher packages. You install only what you need. See Package Hierarchy for the full architecture and the real, current version table on the Compatibility Matrix.

What's the difference between middleware, a registrar, and an extension?

Middleware (the default, ~99% of capability) processes requests — it runs on every request in the order you register it via app.use(). A registrar (~0.9%) is a plain function you call once to wire a subsystem, such as registerControllers. An extension (~0.1%, rare) is a long-lived, app-scoped service with its own boot/teardown lifecycle, registered with app.extend() and booted with app.ready() — the event bus is the canonical example. See Middleware and Extensions for the full taxonomy, or the Glossary for short definitions.

Development

How do I set up hot reload?

Use the @nextrush/dev CLI:

nextrush dev

This watches for file changes and restarts your server automatically. See the Dev Tools guide.

How do I validate request data?

Use @nextrush/validation — it works with any Standard Schema library (Zod, Valibot, ArkType):

import { validate } from '@nextrush/validation';
import { z } from 'zod';

const CreateUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

router.post('/users', validate(CreateUserSchema), (ctx) => {
  ctx.json(ctx.body); // validated + coerced
});

For class-based controllers, the @Body({ transform }) decorator works the same way with a schema's parseAsync. See the Validation guide for both styles.

How do I handle errors?

Throw typed error classes from @nextrush/errors:

import { NotFoundError } from '@nextrush/errors';

if (!user) throw new NotFoundError('User not found');
// → 404 { "error": "NotFoundError", "message": "User not found", "code": "NOT_FOUND", "status": 404 }

See the Error Handling guide and the Troubleshooting catalog for common error-related gotchas.

How do I test my NextRush app?

See the Testing guide for integration-test patterns against a running handler chain, and @nextrush/testing for the class-runtime test harness (createTestModule().override().compile()).

Performance

How fast is NextRush?

Benchmark numbers are currently being re-measured on a clean, CPU-pinned environment with a hardened, parity-validated harness — earlier figures came from single-run sessions on a shared machine and were not reproducible to a publishable standard, so they were withdrawn. There is no current published RPS figure to cite here. See Performance for the methodology, fairness guarantees, and how to run the suite (apps/benchmark) yourself for numbers on your own hardware.

Why might Fastify be faster on some scenarios?

Fastify uses AOT JSON serialization with fast-json-stringify, a highly optimized C-level HTTP parser, and compiled JSON Schema validation. NextRush uses native JSON.stringify and the standard Node.js parser. Any specific gap is hardware- and scenario-dependent — see Performance for the current, honest methodology rather than a fixed number.

Does adding middleware slow things down?

NextRush's compose() pre-compiles the middleware pipeline, so per-middleware overhead is small relative to routing and I/O — but the exact magnitude is exactly what the benchmark re-measurement in progress will quantify. See Performance for current status and Performance Tuning for production guidance.

Deployment

Which runtimes does NextRush support?

See the Compatibility Matrix for the full, regularly re-derived package/version table.

How do I deploy to production?

See the Deployment guide for Node.js, Bun, Deno, Edge, and Docker — including a build-tested Dockerfile.

Migration

Can I migrate from Express?

Yes. The main changes are:

• Replace (req, res, next) with a single ctx object
• Replace res.json() with ctx.json()
• Replace req.params with ctx.params
• Wrap middleware to use await ctx.next() instead of a next() callback

See the Migration guide for step-by-step instructions.

Can I use Express middleware with NextRush?

Not directly — Express middleware uses (req, res, next) while NextRush uses (ctx). Most middleware can be wrapped in a few lines. Common patterns (CORS, helmet, body-parser, rate-limit) have native NextRush packages that are faster and type-safe.

Community

How do I contribute?

See the Contributing guide. NextRush uses pnpm workspaces with Turborepo. Run pnpm install to set up, pnpm test to run tests, and pnpm typecheck for type checking.

Where do I report bugs?

Open an issue on GitHub. Include your Node.js version, NextRush version, and a minimal reproduction. Check Troubleshooting first — your error may already have a documented fix.

Is there a Discord or community chat?

Community channels are being set up. Follow the GitHub repository for announcements.