Next.js

1. Next.js route
3. handle()
5. NextRush engine
7. Your app
9. Response

Why this exists

Traditional Next.js API routes put everything in one file — logic, middleware, validation, error handling — per endpoint. Seven endpoints means seven files, each reimplementing the same patterns:

Traditional Next API                    NextRush inside Next.js

app/api/users/route.ts                  app/api/[[...route]]/route.ts
  GET  → logic                            handle(app)  ← one line, seven exports
  POST → logic
app/api/posts/route.ts                  src/server/app.ts
  GET  → logic                            createApp() + createRouter()
  POST → logic                            middleware, validation, error handling
app/api/comments/route.ts                 — grows without touching route.ts
  GET  → logic
  POST → logic

With NextRush, route.ts never grows. Your routers, middleware, and services live in src/server/ and compose the same way they would under listen().

Before you begin

• ✓ A terminal and a package manager
• ✓ An existing Next.js App Router project (14, 15, or 16) — or a fresh one from create-next-app
• ✓ You already know how to run next dev
• ✓ ~15 minutes

$ pnpm add nextrush @nextrush/adapter-nextjs

import { createApp, createRouter } from 'nextrush';

const app = createApp();

const api = createRouter();
api.get('/hello', (ctx) => ctx.json({ message: 'Hello Next.js!' }));
app.route('/api', api);

export { app };

import { app } from '@/server/app';
import { handle } from 'nextrush/nextjs';

export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } = handle(app);

next dev

Request → Next.js middleware → route.ts → handle() → NextRush middleware → Router → Response

import { createApp, createRouter } from 'nextrush';
import { logger } from '@nextrush/logger';

const app = createApp();
app.use(logger()); // ← runs on every request, same under listen() and Next.js

const api = createRouter();
api.get('/hello', (ctx) => ctx.json({ message: 'Hello Next.js!' }));
app.route('/api', api);

export { app };

import type { Context, NextFunction } from 'nextrush';

export async function auth(ctx: Context, next: NextFunction) {
  const token = ctx.headers.authorization?.replace('Bearer ', '');
  if (!token) {
    ctx.throw(401, 'Missing authorization token');
    return;
  }

  const user = await verifyToken(token);
  if (!user) {
    ctx.throw(401, 'Invalid or expired token');
    return;
  }

  ctx.state.user = user; // available in every downstream handler
  await next();
}

// Global — every route requires auth:
app.use(auth);

// Or per-router — only these routes require auth:
const protectedRouter = createRouter();
protectedRouter.use(auth);
protectedRouter.get('/me', (ctx) => ctx.json(ctx.state.user));

import type { Context, NextFunction } from 'nextrush';

export async function errorHandler(ctx: Context, next: NextFunction) {
  try {
    await next();
  } catch (err: any) {
    const status = err.status || err.statusCode || 500;
    ctx.status = status;
    ctx.json({
      error: err.message || 'Internal server error',
      status,
    });
  }
}

app.use(errorHandler); // register FIRST — wraps everything

// Now any handler can throw:
api.get('/users/:id', async (ctx) => {
  const user = await findUser(ctx.params.id);
  if (!user) ctx.throw(404, 'User not found'); // → { error: "User not found", status: 404 }
  ctx.json(user);
});

import { cors, devCors, strictCors } from '@nextrush/cors';

// Development — allows localhost origins:
app.use(devCors());

// Production — explicit origins:
app.use(cors({ origin: ['https://my-frontend.com'] }));

// Strict — credentials + specific origins + max-age:
app.use(strictCors({ origins: ['https://my-frontend.com'], credentials: true }));

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

const CreateUser = {
  body: {
    name: { type: 'string', minLength: 1 },
    email: { type: 'string', format: 'email' },
  },
};

usersRouter.post('/users', validate(CreateUser), async (ctx) => {
  // ctx.body is validated and typed
  const user = await createUser(ctx.body);
  ctx.status(201).json(user);
});

import { rateLimit } from '@nextrush/rate-limit';

// Global — 100 requests per minute per IP:
app.use(rateLimit({ windowMs: 60_000, max: 100 }));

// Per-route — stricter for auth endpoints:
authRouter.post('/login', rateLimit({ windowMs: 15 * 60_000, max: 5 }), loginHandler);

🎉Next.js integration complete — a real NextRush app running inside Next.js. The route file will never need to change.

Checkpoint

Confirm the route answers:

curl -i http://localhost:3000/api/hello
# → HTTP/1.1 200 OK
# → {"message":"Hello Next.js!"}

Your project now looks like:

✓Baseline complete — the bridge is working. The route file will never need to change no matter how large src/server/app.ts grows.

Mental model

The request is never touched. handle() forwards it, unmodified, through the same request-handling engine every edge/serverless target already uses:

Rule: mount prefixes belong to your application (app.route(prefix, router)) — this package never infers or strips one. That's why "Build the app"'s app.route('/api', api) and "Mount it"'s folder (app/api/[[...route]]/) both had to agree.

Growing past one route

A real API is more than one route file. Split by feature, keep business logic out of route handlers, mount everything once in src/server/app.ts:

// Pure business logic — no ctx, no Request/Response.
export async function findUser(id: string) {
  return db.user.findUnique({ where: { id } });
}

// HTTP concerns only — delegates to the service.
import { createRouter } from 'nextrush';
import { findUser } from '../services/users.service';

export const usersRouter = createRouter();

usersRouter.get('/:id', async (ctx) => {
  const user = await findUser(ctx.params.id);
  if (!user) return ctx.throw(404, 'User not found');
  ctx.json(user);
});

// The one place every router gets mounted.
import { createApp } from 'nextrush';
import { usersRouter } from './routes/users.route';
import { postsRouter } from './routes/posts.route';

const app = createApp();
app.route('/api/users', usersRouter);
app.route('/api/posts', postsRouter);

export { app };

route.ts stays exactly as it was in "Mount it with handle()" — the identical src/server/app.ts also boots unchanged under listen() or any other adapter.

Advanced: class-based apps (DI, modules, guards)

handle() also accepts a factory instead of a plain app — useful when your app needs an async boot step like await registerModule(...):

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

@Service()
class UserService {
  findAll() { return [{ id: 1, name: 'Alice' }]; }
}

@Controller('/users')
class UserController {
  constructor(private users: UserService) {}
  @Get() findAll() { return this.users.findAll(); }
}

@Module({ controllers: [UserController], providers: [UserService] })
export class AppModule {}

import { createApp } from 'nextrush';
import { registerModule } from 'nextrush/class';
import { handle } from 'nextrush/nextjs';
import { AppModule } from '@/server/app.module';

export const { GET, POST } = handle(async () => {
  const app = createApp();
  await registerModule(app, AppModule, { prefix: '/api' });
  return app;
});

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Troubleshooting

import { createApp } from 'nextrush';

const app = createApp({ debug: true }); // logs middleware chain, routing, and timing

api.get('/debug', (ctx) => {
  ctx.json({
    path: ctx.path,           // the real URL path, not a rewritten one
    method: ctx.method,
    headers: Object.fromEntries(Object.entries(ctx.headers)),
    runtime: ctx.runtime,     // 'node' under Next.js
  });
});

[NextRush] Mount prefix mismatch: app.route('/api', ...) but the route file is at app/api/[[...route]]/route.ts

import { app } from '../app';

test('GET /api/hello returns greeting', async () => {
  const res = await app.inject({ method: 'GET', path: '/api/hello' });
  expect(res.status).toBe(200);
  expect(res.json()).toEqual({ message: 'Hello Next.js!' });
});

export const dynamic = 'force-dynamic';

FAQ

Does create-nextrush scaffold a Next.js project? No — use Next's own create-next-app. This package documents how to wire NextRush into it.

Can I use this without the nextrush meta-package? Yes — install @nextrush/adapter-nextjs directly and pass any @nextrush/core Application to handle().

Does it work on Bun, Deno, or Cloudflare (via OpenNext)? Yes — the package is fully Web-standard, no node:* or runtime globals.

Does Next.js support decorators? Its SWC compiler does — enable experimentalDecorators/emitDecoratorMetadata in tsconfig.json. See the class-based section above.

Does it support the Pages Router? No — App Router only. The Pages Router hands (req, res), not a Request.

How do I test the mounted app? Test src/server/app.ts the same way you'd test any NextRush app — it's a plain Application that doesn't know about Next.js. Import it, call app.inject() (or your preferred test helper), and assert on the response. The bridge in route.ts is one line and doesn't need its own test — Next's own routing handles that.

How do I share auth between Next.js pages and the NextRush API? The NextRush app runs inside the same Next.js process, so it shares the same environment and cookies. Read the session from ctx.headers (the cookie header is forwarded unmodified) or pass the session token from your Next.js middleware via ctx.state. The adapter never strips or rewrites headers — what Next.js sends is what your NextRush handler sees.

What you learned

• ✓ One handle() bridges your entire NextRush app — seven exports, zero configuration
• ✓ Mount prefixes belong to your app (app.route(prefix, router)) — keep them in sync with the folder
• ✓ A real API is multiple files — routers, services, and app.ts grow independently of the bridge
• ✓ ctx.waitUntil() needs this adapter to work under Next.js — without it, background work silently no-ops
• ✓ Next.js middleware runs before handle(); NextRush middleware runs after — they don't interfere
• ✓ The same src/server/app.ts boots unchanged under listen() or any other adapter

Next steps

Continue learning