mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
84f1e44d4d
Note: re-apply of #92817 ### What? Deprecates the Edge Runtime and the `preferredRegion` route segment config that only applied to edge runtime with build-time warnings, TypeScript IDE hints, error documentation pages, and documentation updates. ### Why? Edge Runtime in Next.js is being deprecated in favor of the Node.js runtime (the default). The `preferredRegion` route segment config is tightly coupled to Edge Runtime and is also being deprecated. ### How? **Edge Runtime deprecation:** - Added `warnAboutEdgeRuntime()` helper using `Log.warnOnce` in `packages/next/src/build/warn-about-edge-runtime.ts` - Warning fires in `get-page-static-info.ts` (Webpack dev/build + Turbopack build) and `turbopack-utils.ts` (Turbopack dev) when `runtime = 'edge'` is detected - Marked `'edge'` as `@deprecated` in the TypeScript language service plugin (`rules/config.ts`) - Created `errors/edge-runtime-deprecated.mdx` with migration guidance - Updated documentation across 11 files to add deprecation notices or simplify/remove outdated Edge Runtime references **`preferredRegion` deprecation:** - Added `warnAboutPreferredRegion()` helper in the same file - Warning fires in `get-page-static-info.ts` for both App Router (`config.preferredRegion`) and Pages Router (`config.config?.regions`) - Marked `preferredRegion` as `@deprecated` in the TypeScript language service plugin and the generated types (`next-types-plugin`) - Created `errors/preferred-region-deprecated.mdx` with migration guidance (remove the export) - Updated documentation across 4 files to add deprecation notices **Tests:** - Added `test/e2e/edge-runtime-deprecated/` with fixture and assertions for the edge runtime warning (dev + production) - Added `test/production/preferred-region-deprecated/` with fixture and assertions for the preferredRegion warning (production only -- Turbopack dev does not surface `preferredRegion` from the Rust layer to JS) <!-- NEXT_JS_LLM_PR --> --------- Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
96 lines
3.8 KiB
Plaintext
96 lines
3.8 KiB
Plaintext
---
|
|
title: Invoking Entrypoints
|
|
description: Invoke Node.js and Edge build entrypoints with adapter runtime context.
|
|
---
|
|
|
|
Build output entrypoints use a `handler(..., ctx)` interface, with runtime-specific request/response types.
|
|
|
|
## Node.js runtime (`runtime: 'nodejs'`)
|
|
|
|
Node.js entrypoints use the following interface:
|
|
|
|
```typescript
|
|
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`:
|
|
|
|
```ts
|
|
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:
|
|
|
|
- [`packages/next/src/build/templates/app-page.ts`](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/templates/app-page.ts)
|
|
- [`packages/next/src/build/templates/app-route.ts`](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/templates/app-route.ts)
|
|
- and [`packages/next/src/build/templates/pages-api.ts`](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/templates/pages-api.ts)
|
|
|
|
## Edge runtime (`runtime: 'edge'`) (deprecated)
|
|
|
|
> The Edge Runtime is [deprecated](/docs/messages/edge-runtime-deprecated). New routes should use the Node.js runtime.
|
|
|
|
Edge entrypoints use the following interface:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
{
|
|
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:
|
|
|
|
```ts
|
|
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:
|
|
|
|
- [`packages/next/src/build/templates/edge-ssr.ts`](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/templates/edge-ssr.ts)
|
|
- [`packages/next/src/build/templates/edge-app-route.ts`](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/templates/edge-app-route.ts)
|
|
- [`packages/next/src/build/templates/pages-edge-api.ts`](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/templates/pages-edge-api.ts)
|
|
- and [`packages/next/src/build/templates/middleware.ts`](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/templates/middleware.ts)
|