mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
c754d9fb6e
<!-- Thanks for opening a PR! Your contribution is much appreciated. To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below. Choose the right checklist for the change(s) that you're making: ## For Contributors ### Improving Documentation - Run `pnpm prettier-fix` to fix formatting issues before opening the PR. - Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide ### Adding or Updating Examples - The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md - Make sure the linting passes by running `pnpm build && pnpm lint`. See https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md ### Fixing a bug - Related issues linked using `fixes #number` - Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Adding a feature - Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas) - Related issues/discussions are linked using `fixes #number` - e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs) - Documentation added - Telemetry added. In case of a feature if it's used or not. - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ## For Maintainers - Minimal description (aim for explaining to someone not on the team to understand the PR) - When linking to a Slack thread, you might want to share details of the conclusion - Link both the Linear (Fixes NEXT-xxx) and the GitHub issues - Add review comments if necessary to explain to the reviewer the logic behind a change ### What? Update the edge-and-nodejs-runtime doc with a Good to Know about a common build error involving using packages that rely on the filesystem in an edge runtime environment. ### Why? The docs don't mention the issue. Most github issues, articles, and SO answers revolve around updating the next.config with a webpack key to ignore 'fs' imports in api routes and getServerSideProps functions. This is incorrect when the issue is using packages that rely on 'fs', 'stream', or 'path' in an edge runtime environment. Silly mistake, but it costs people time. ### How? Update the docs. Closes NEXT- Fixes # --> --------- Co-authored-by: Delba de Oliveira <[email protected]>
85 lines
6.6 KiB
Plaintext
85 lines
6.6 KiB
Plaintext
---
|
|
title: Edge and Node.js Runtimes
|
|
description: Learn about the switchable runtimes (Edge and Node.js) in Next.js.
|
|
---
|
|
|
|
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
|
|
|
In the context of Next.js, runtime refers to the set of libraries, APIs, and general functionality available to your code during execution.
|
|
|
|
On the server, there are two runtimes where parts of your application code can be rendered:
|
|
|
|
- The **Node.js Runtime** (default) has access to all Node.js APIs and compatible packages from the ecosystem.
|
|
- The **Edge Runtime** is based on [Web APIs](/docs/app/api-reference/edge).
|
|
|
|
## Runtime Differences
|
|
|
|
There are many considerations to make when choosing a runtime. This table shows the major differences at a glance. If you want a more in-depth analysis of the differences, check out the sections below.
|
|
|
|
| | Node | Serverless | Edge |
|
|
| ------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---------- | ---------------- |
|
|
| Cold Boot | / | Normal | Low |
|
|
| [HTTP Streaming](/docs/app/building-your-application/routing/loading-ui-and-streaming) | Yes | Yes | Yes |
|
|
| IO | All | All | `fetch` |
|
|
| Scalability | / | High | Highest |
|
|
| Security | Normal | High | High |
|
|
| Latency | Normal | Low | Lowest |
|
|
| npm Packages | All | All | A smaller subset |
|
|
| [Static Rendering](/docs/app/building-your-application/rendering/server-components#static-rendering-default) | Yes | Yes | No |
|
|
| [Dynamic Rendering](/docs/app/building-your-application/rendering/server-components#dynamic-rendering) | Yes | Yes | Yes |
|
|
| [Data Revalidation w/ `fetch`](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#revalidating-data) | Yes | Yes | Yes |
|
|
|
|
### Edge Runtime
|
|
|
|
In Next.js, the lightweight Edge Runtime is a subset of available Node.js APIs.
|
|
|
|
The Edge Runtime is ideal if you need to deliver dynamic, personalized content at low latency with small, simple functions. The Edge Runtime's speed comes from its minimal use of resources, but that can be limiting in many scenarios.
|
|
|
|
For example, code executed in the Edge Runtime [on Vercel cannot exceed between 1 MB and 4 MB](https://vercel.com/docs/concepts/limits/overview#edge-middleware-and-edge-functions-size), this limit includes imported packages, fonts and files, and will vary depending on your deployment infrastructure. In addition, the Edge Runtime does not support all Node.js APIs meaning some `npm` packages may not work. For example, "Module not found: Can't resolve 'fs'" or similar errors. We recommend using the Node.js runtime if you need to use these APIs or packages.
|
|
|
|
### Node.js Runtime
|
|
|
|
Using the Node.js runtime gives you access to all Node.js APIs, and all npm packages that rely on them. However, it's not as fast to start up as routes using the Edge runtime.
|
|
|
|
Deploying your Next.js application to a Node.js server will require managing, scaling, and configuring your infrastructure. Alternatively, you can consider deploying your Next.js application to a serverless platform like Vercel, which will handle this for you.
|
|
|
|
### Serverless Node.js
|
|
|
|
Serverless is ideal if you need a scalable solution that can handle more complex computational loads than the Edge Runtime. With Serverless Functions on Vercel, for example, your overall code size is [50MB](https://vercel.com/docs/concepts/limits/overview#serverless-function-size) including imported packages, fonts, and files.
|
|
|
|
The downside compared to routes using the [Edge](https://vercel.com/docs/concepts/functions/edge-functions) is that it can take hundreds of milliseconds for Serverless Functions to boot up before they begin processing requests. Depending on the amount of traffic your site receives, this could be a frequent occurrence as the functions are not frequently "warm".
|
|
|
|
<AppOnly>
|
|
|
|
## Examples
|
|
|
|
### Segment Runtime Option
|
|
|
|
You can specify a runtime for individual route segments in your Next.js application. To do so, [declare a variable called `runtime` and export it](/docs/app/api-reference/file-conventions/route-segment-config). The variable must be a string, and must have a value of either `'nodejs'` or `'edge'` runtime.
|
|
|
|
The following example demonstrates a page route segment that exports a `runtime` with a value of `'edge'`:
|
|
|
|
```tsx filename="app/page.tsx" switcher
|
|
export const runtime = 'edge' // 'nodejs' (default) | 'edge'
|
|
```
|
|
|
|
```jsx filename="app/page.js" switcher
|
|
export const runtime = 'edge' // 'nodejs' (default) | 'edge'
|
|
```
|
|
|
|
You can also define `runtime` on a layout level, which will make all routes under the layout run on the edge runtime:
|
|
|
|
```tsx filename="app/layout.tsx" switcher
|
|
export const runtime = 'edge' // 'nodejs' (default) | 'edge'
|
|
```
|
|
|
|
```jsx filename="app/layout.js" switcher
|
|
export const runtime = 'edge' // 'nodejs' (default) | 'edge'
|
|
```
|
|
|
|
If the segment runtime is _not_ set, the default `nodejs` runtime will be used. You do not need to use the `runtime` option if you do not plan to change from the Node.js runtime.
|
|
|
|
</AppOnly>
|
|
|
|
> Please refer to the [Node.js Docs](https://nodejs.org/docs/latest/api/) and [Edge Docs](/docs/app/api-reference/edge) for the full list of available APIs. Both runtimes can also support [streaming](/docs/app/building-your-application/routing/loading-ui-and-streaming) depending on your deployment infrastructure.
|