DocumentationShowcaseBlog

Invoking Entrypoints

Invoke JavaScript build handlers and experimental Go HTTP server entrypoints.

Node.js and Edge entrypoints use a handler(..., ctx) interface, with runtime-specific request/response types. Experimental Go entrypoints are compiled HTTP servers.

Node.js runtime (runtime: 'nodejs')

Node.js entrypoints use the following interface:

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

When invoking Node.js entrypoints directly, adapters can pass helpers directly on requestMeta instead of relying on internals. Some of the supported fields are hostname, revalidate, and render404:

await handler(req, res, {
  requestMeta: {
    // Relative path from process.cwd() to the Next.js project directory.
    relativeProjectDir: '.',
    // Optional hostname used by route handlers when constructing absolute URLs.
    hostname: '127.0.0.1',
    // Optional internal revalidate function to avoid revalidating over the network
    revalidate: async ({ urlPath, headers, opts }) => {
      // platform-specific revalidate implementation
    },
    // Optional function to render the 404 page for pages router `notFound: true`
    render404: async (req, res, parsedUrl, setHeaders) => {
      // platform-specific 404 rendering implementation
    },
  },
})

Relevant files in the Next.js core:

Edge runtime (runtime: 'edge') (deprecated)

The Edge Runtime is deprecated. New routes should use the Node.js runtime.

Edge entrypoints use the following interface:

handler(
  request: Request,
  ctx: {
    waitUntil?: (prom: Promise<void>) => void
    signal?: AbortSignal
    requestMeta?: RequestMeta
  }
): Promise<Response>

The shape is aligned around handler(..., ctx), but Node.js and Edge runtimes use different request/response primitives.

For outputs with runtime: 'edge', Next.js also provides output.edgeRuntime with the canonical metadata needed to invoke the entrypoint:

{
  modulePath: string // Absolute path to the module registered in the edge runtime
  entryKey: string // Canonical key used by the edge entry registry
  handlerExport: string // Export name to invoke, currently 'handler'
}

After your edge runtime loads and evaluates the chunks for modulePath, use entryKey to read the registered entry from the global edge entry registry (globalThis._ENTRIES), then invoke handlerExport from that entry:

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

Use edgeRuntime instead of deriving registry keys or handler names from filenames.

Relevant files in the Next.js core:

Go runtime (runtime: 'go')

With experimental route.go handlers, output.filePath identifies a native executable rather than a JavaScript module. Package it with the declared assets for the target operating system and architecture, preserving executable permissions and the asset destination paths.

The executable targets the build host's operating system and architecture, with CGO disabled. Build in an environment that matches the deployment runtime. Cross-compilation is not supported for Go routes.

Start the executable without arguments, set PORT to its assigned HTTP port, and use the packaged function directory as its working directory. The server listens on 0.0.0.0 so container and function ingress can reach it. The adapter owns network isolation. The adapter build's executable runs independently of the self-hosted Next.js server: it requires neither a private Next.js token nor a parent-owned stdin pipe.

Forward the final destination URL after rewrites and proxy processing, including its query string and any basePath. For example, a request for /alias?sort=asc rewritten to /users/123 must reach the Go server as /users/123?sort=asc. The handler's r.URL, r.RequestURI, and query reflect that destination, including any URL normalization the platform performs. Development and self-hosted deployments use the same destination URL contract.

Each executable contains only its own emitted route pattern. It matches the destination pathname and derives decoded dynamic and catch-all parameters from it. Escaped slashes stay within their original parameter segments. A pathname that does not match the emitted route returns 404.

The platform routes requests to the correct Go function and runs its own rewrite and proxy integration. Node.js outputs continue to use their existing handler interface. JavaScript callbacks such as ctx.waitUntil cannot be passed to the Go process; the initial server contract provides no completion guarantee for post-response work.

On this page