Next.js

Bridge a NextRush Application into the seven exports a Next.js App Router route.ts needs — one function, zero request rewriting.

Installation

$ pnpm add @nextrush/adapter-nextjs

Already using nextrush? Import from nextrush/nextjs instead — same package, re-exported as an optional peer. A functional-only pnpm add nextrush never resolves it or next.

Quick reference

// src/server/app.ts
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 };

// app/api/[[...route]]/route.ts
import { app } from '@/server/app';
import { handle } from 'nextrush/nextjs';

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

For the full walkthrough — project structure, class-based apps, the Next 14 caching caveat — see the Next.js tutorial.

API reference

handle(app, options?)

Mounts an Application and returns all seven Next.js App Router HTTP-method exports.

import { handle } from 'nextrush/nextjs';

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

Also accepts a factory — sync or async — for apps that need to build asynchronously (class-based apps registering modules, for example). AppModule is an ordinary @Module class — see the modules concept for how @Module/@Controller/@Service compose, and the Next.js tutorial for the full, runnable version of this example:

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

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

type AppSource

An Application, or a (possibly async) factory producing one:

type AppSource = Application | (() => Application | Promise<Application>);

type NextRouteHandlers

The shape handle() returns — exactly the seven methods Next.js route handlers support:

type NextRouteHandlers = {
  GET: RouteHandlerFn;
  POST: RouteHandlerFn;
  PUT: RouteHandlerFn;
  PATCH: RouteHandlerFn;
  DELETE: RouteHandlerFn;
  HEAD: RouteHandlerFn;
  OPTIONS: RouteHandlerFn;
};

type NextRouteContext

The structural shape of Next's second handler argument — matches Next's own generated RouteContext type (params as a Promise, per Next 15+'s async-params convention):

type NextRouteContext = {
  params: Promise<Record<string, string | string[] | undefined>>;
};

Options

Both options are pass-throughs to @nextrush/adapter-edge's createFetchHandler — this package adds no timeout or error-handling logic of its own (see Mental model below).

Mental model

handle() resolves the Application once (memoized for the life of the module instance), builds one createFetchHandler engine over it, and returns seven functions that all dispatch through that same engine. It adds no execution model, no context type, and no error handling of its own — every one of those is inherited from @nextrush/adapter-edge unmodified.

Invariant: the request forwarded to the engine is never modified — no Request reconstruction, ever. Mount prefixes are declared by the application (app.route()), never inferred or configured by this package.

ctx.waitUntil() and after()

Next.js supplies no execution context of its own the way Cloudflare or Vercel Edge do — without this adapter, ctx.waitUntil() silently no-ops under a hand-rolled bridge. handle() resolves Next's after() export as a capability probe (once, process-lifetime) and wires ctx.waitUntil() to it automatically when available:

app.use(async (ctx) => {
  ctx.waitUntil(
    fetch('https://analytics.example.com/track', {
      method: 'POST',
      body: JSON.stringify({ path: ctx.path }),
    })
  );

  ctx.json({ ok: true });
});

Compatibility

Requirements

Runtimes

Integration

• Peer dependencies: next >=14.0.0 (optional, resolved lazily)
• Depends on: @nextrush/adapter-edge — reuses its fetch engine, unmodified
• Works with: any NextRush middleware/class-runtime package — the mounted app is an ordinary Application
• Incompatible with: the Pages Router — see rejected alternatives

Rejected alternatives

Recorded here because each was seriously considered during design — not obvious in hindsight:

Full design history: RFC-024, ADR-0014.

Related

• Next.js tutorial — the full walkthrough: installation, project structure for a real API, class-based apps, and the Next 14 caching caveat.
• Platforms overview — understanding runtime adapters generally.
• @nextrush/adapter-edge — the fetch-handler engine this package builds on, unmodified.
• @nextrush/adapter-serverless — for AWS Lambda/GCF/Azure Functions deployments with no Next.js involved.