Invoking Entrypoints

Core Idea

Build output entrypoints expose a handler(..., ctx) function; the exact request/response types differ between the Node.js runtime and the deprecated Edge runtime.

Key Concepts

• Node.js handler signature: handler(req: IncomingMessage, res: ServerResponse, ctx: { waitUntil?, requestMeta? }).
• requestMeta helpers (Node.js): relativeProjectDir, hostname, revalidate({ urlPath, headers, opts }), render404(req, res, parsedUrl, setHeaders) — adapters can pass these directly instead of relying on internals.
• Edge handler signature (deprecated): handler(request: Request, ctx: { waitUntil?, signal?, requestMeta? }): Promise<Response>.
• output.edgeRuntime: canonical metadata for edge outputs — { modulePath, entryKey, handlerExport } — used instead of deriving registry keys from filenames.
• globalThis._ENTRIES: the global edge entry registry; after loading modulePath's chunks, look up entryKey here to get the module, then call handlerExport.

Code Examples

handler(
  req: IncomingMessage,
  res: ServerResponse,
  ctx: {
    waitUntil?: (promise: Promise<void>) => void
    requestMeta?: RequestMeta
  }
): Promise<void>

await handler(req, res, {
  requestMeta: {
    relativeProjectDir: '.',
    hostname: '127.0.0.1',
    revalidate: async ({ urlPath, headers, opts }) => {
      // platform-specific revalidate implementation
    },
    render404: async (req, res, parsedUrl, setHeaders) => {
      // platform-specific 404 rendering implementation
    },
  },
})

// Edge: invoke via the global entry registry using edgeRuntime metadata
const entry = await globalThis._ENTRIES[output.edgeRuntime.entryKey]
const handler = entry[output.edgeRuntime.handlerExport]
await handler(request, ctx)

• O que demonstra: assinatura Node.js do handler com requestMeta helpers, e o padrão canônico de invocação de handlers Edge via edgeRuntime + globalThis._ENTRIES.

Reference Tables

Runtime	Handler signature	Status
nodejs	handler(req, res, ctx) (IncomingMessage/ServerResponse)	Default, recommended
edge	handler(request, ctx) (Request → Promise<Response>)	Deprecated, use nodejs for new routes

Anti-patterns

• Deriving edge registry keys/handler names from filenames: fragile across builds; always use output.edgeRuntime.entryKey/handlerExport.
• Building new routes targeting the Edge runtime: it's deprecated; prefer runtime: 'nodejs'.

Key Takeaways

1. Node.js and Edge entrypoints share the handler(..., ctx) shape but use incompatible request/response primitives — adapters must branch by runtime.
2. requestMeta is the extension point for platform-specific behavior (revalidate, 404 rendering, hostname) without touching Next.js internals.
3. Edge runtime invocation always goes through globalThis._ENTRIES[entryKey][handlerExport], sourced from output.edgeRuntime.

Connects To

• ch283 edge-runtime: the API surface available inside Edge-runtime handlers.
• ch279 output-types: where edgeRuntime metadata appears on each output type.