Invoking Entrypoints

Core Idea

How adapters invoke Next.js's build output entrypoints at runtime, with distinct interfaces for the Node.js runtime and the (deprecated) Edge runtime.

Key Concepts

• Node.js entrypoints (runtime: 'nodejs'): handler(req: IncomingMessage, res: ServerResponse, ctx: { waitUntil?, requestMeta? }).
• requestMeta helper fields: relativeProjectDir, hostname (for absolute URL construction), revalidate (custom async revalidate implementation), render404 (custom 404 rendering for Pages Router notFound: true).
• Edge entrypoints (runtime: 'edge', deprecated): handler(request: Request, ctx: { waitUntil?, signal?, requestMeta? }): Promise<Response>.
• output.edgeRuntime: canonical metadata for edge outputs — modulePath, entryKey, handlerExport (currently always 'handler'); use this instead of deriving keys from filenames.
• globalThis._ENTRIES: global edge entry registry read using entryKey after loading modulePath's chunks.

Code Examples

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
    },
  },
})

• O que demonstra: invocação direta de um entrypoint Node.js passando helpers em requestMeta em vez de depender de internals.

const entry = await globalThis._ENTRIES[output.edgeRuntime.entryKey]
const handler = entry[output.edgeRuntime.handlerExport]
await handler(request, ctx)

• O que demonstra: como invocar um entrypoint Edge usando a metadata canônica de output.edgeRuntime.

Anti-patterns

• Derivar chaves de registro ou nomes de handler a partir de nomes de arquivo: use sempre edgeRuntime.entryKey/handlerExport.
• Construir novos entrypoints Edge: runtime deprecated; use Node.js pra novas rotas.

Key Takeaways

1. Node.js e Edge usam primitivos de request/response diferentes (IncomingMessage/ServerResponse vs. Request/Response), mas ambos seguem o padrão handler(..., ctx).
2. Edge Runtime está deprecated; novas rotas devem usar Node.js runtime.
3. output.edgeRuntime existe em qualquer output com runtime: 'edge', dando a metadata exata pra invocação correta.

Connects To

• Output Types (ch441): cada tipo de output inclui edgeRuntime quando runtime: 'edge'.
• Runtime Integration (ch439): contexto de ctx.waitUntil/requestMeta usado aqui.