From 0b81b455257ad9bf05dcba027cc0945ea1d3ddcf Mon Sep 17 00:00:00 2001 From: Amy Burns Date: Wed, 7 Dec 2022 12:38:03 +0000 Subject: [PATCH 1/4] updating errors and information on the edge runtime --- .../react-18/switchable-runtime.md | 40 ++++++------------- docs/api-routes/edge-api-routes.md | 2 + .../data-fetching/get-server-side-props.md | 12 ++++++ .../incremental-static-regeneration.md | 2 +- .../returning-response-body-in-middleware.md | 2 + 5 files changed, 30 insertions(+), 28 deletions(-) diff --git a/docs/advanced-features/react-18/switchable-runtime.md b/docs/advanced-features/react-18/switchable-runtime.md index cdd5268e825d..0fe779f8bdbe 100644 --- a/docs/advanced-features/react-18/switchable-runtime.md +++ b/docs/advanced-features/react-18/switchable-runtime.md @@ -8,19 +8,6 @@ Next.js has two **server runtimes** where you can render parts of your applicati By default, Next.js uses the Node.js runtime. [Middleware](https://nextjs.org/docs/advanced-features/middleware) and [Edge API Routes](https://nextjs.org/docs/api-routes/edge-api-routes) use the Edge runtime. -## Global Runtime Option - -To configure the runtime for your whole application, you can set the experimental option `runtime` in your `next.config.js` file: - -```js -// next.config.js -module.exports = { - experimental: { - runtime: 'experimental-edge', // 'node.js' (default) | experimental-edge - }, -} -``` - You can detect which runtime you're using by looking at the `process.env.NEXT_RUNTIME` Environment Variable during runtime, and examining the `options.nextRuntime` variable during compilation. ## Page Runtime Option @@ -38,22 +25,21 @@ export const config = { } ``` -When both the per-page runtime and global runtime are set, the per-page runtime overrides the global runtime. If the per-page runtime is _not_ set, the global runtime option will be used. - ## Runtime Differences -|   | Node (Server) | Node (Serverless) | Edge | -| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------- | ---------------- | -| [Cold Boot](https://vercel.com/docs/concepts/get-started/compute#cold-and-hot-boots?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) | / | ~250ms | Instant | -| HTTP Streaming | Yes | Yes | Yes | -| IO | All | All | `fetch` | -| Scalability | / | High | Highest | -| Security | Normal | High | High | -| Latency | Normal | Low | Lowest | -| Code Size | / | 50MB | 1MB | -| NPM Packages | All | All | A smaller subset | - -Next.js' default runtime configuration is good for most use cases, but there’re still many reasons to change to one runtime over the other one. +|   | Node (Server) | Node (Serverless) | Edge | +| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------- | -------------------------------------------------------- | +| Name | `nodejs` | `nodejs` | `edge` or `experimental-edge` if using Next.js Rendering | +| [Cold Boot](https://vercel.com/docs/concepts/get-started/compute#cold-and-hot-boots?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) | / | ~250ms | Instant | +| HTTP Streaming | Yes | Yes | Yes | +| IO | All | All | `fetch` | +| Scalability | / | High | Highest | +| Security | Normal | High | High | +| Latency | Normal | Low | Lowest | +| Code Size | / | 50MB | 1MB | +| NPM Packages | All | All | A smaller subset | + +Next.js' default runtime configuration is good for most use cases, but there are still many reasons to change to one runtime over the other one. For example, for API routes that rely on native Node.js APIs, they need to run with the Node.js Runtime. However, if an API only uses something like cookie-based authentication, using Middleware and the Edge Runtime will be a better choice due to its lower latency as well as better scalability. diff --git a/docs/api-routes/edge-api-routes.md b/docs/api-routes/edge-api-routes.md index ae9378b6f506..208fc3f28f95 100644 --- a/docs/api-routes/edge-api-routes.md +++ b/docs/api-routes/edge-api-routes.md @@ -131,4 +131,6 @@ Edge API Routes use the [Edge Runtime](/docs/api-reference/edge-runtime.md), whe Edge API Routes can [stream responses](/docs/api-reference/edge-runtime.md#web-stream-apis) from the server and run _after_ cached files (e.g. HTML, CSS, JavaScript) have been accessed. Server-side streaming can help improve performance with faster [Time To First Byte (TTFB)](https://web.dev/ttfb/). +> Note: Using [Edge Runtime](/docs/api-reference/edge-runtime.md) with `getServerSideProps` does not give you access to the response object. If you need access to `res`, you should use the [Node.js runtime](/docs/advanced-features/react-18/switchable-runtime.md) by setting `runtime: 'nodejs'`. + View the [supported APIs](/docs/api-reference/edge-runtime.md) and [unsupported APIs](/docs/api-reference/edge-runtime.md#unsupported-apis) for the Edge Runtime. diff --git a/docs/basic-features/data-fetching/get-server-side-props.md b/docs/basic-features/data-fetching/get-server-side-props.md index 3d789e493944..afdac8ad6668 100644 --- a/docs/basic-features/data-fetching/get-server-side-props.md +++ b/docs/basic-features/data-fetching/get-server-side-props.md @@ -45,6 +45,18 @@ It can be tempting to reach for an [API Route](/docs/api-routes/introduction.md) Take the following example. An API route is used to fetch some data from a CMS. That API route is then called directly from `getServerSideProps`. This produces an additional call, reducing performance. Instead, directly import the logic used inside your API Route into `getServerSideProps`. This could mean calling a CMS, database, or other API directly from inside `getServerSideProps`. +### getServerSideProps with Edge API Routes + +`getServerSideProps` can be used with both Serverless and Edge Runtimes, and you can set props in both. However, currently in Edge Runtime, you do not have access to the response object. This means that you cannot — for example — add cookies in `getServerSideProps`. To have access to the response object, you should continue to use the Serverless runtime, which is the default runtime. + +You can set the runtime on a [per-page basis](https://nextjs.org/docs/advanced-features/react-18/switchable-runtime#page-runtime-option) by modifying the `config`, for example: + +``` +export const config = { + runtime: 'nodejs' +} +``` + ## Fetching data on the client side If your page contains frequently updating data, and you don’t need to pre-render the data, you can fetch the data on the [client side](/docs/basic-features/data-fetching/client-side.md). An example of this is user-specific data: diff --git a/docs/basic-features/data-fetching/incremental-static-regeneration.md b/docs/basic-features/data-fetching/incremental-static-regeneration.md index a4bc788533d3..498a5bdf9365 100644 --- a/docs/basic-features/data-fetching/incremental-static-regeneration.md +++ b/docs/basic-features/data-fetching/incremental-static-regeneration.md @@ -27,7 +27,7 @@ description: 'Learn how to create or update static pages at runtime with Increme Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages. -> Note: the `experimental-edge` runtime (https://nextjs.org/docs/api-reference/edge-runtime) is currently not compatible with ISR although can leverage `stale-while-revalidate` by setting the `cache-control` header manually. +> Note: the [`experimental-edge` runtime](https://nextjs.org/docs/api-reference/edge-runtime) is currently not compatible with ISR although can leverage `stale-while-revalidate` by setting the `cache-control` header manually. To use ISR, add the `revalidate` prop to `getStaticProps`: diff --git a/errors/returning-response-body-in-middleware.md b/errors/returning-response-body-in-middleware.md index 344ce1b278f9..57c999039272 100644 --- a/errors/returning-response-body-in-middleware.md +++ b/errors/returning-response-body-in-middleware.md @@ -1,5 +1,7 @@ # Returning response body in Middleware +> Note: In Next.js v13.0.0 you can now respond to middleware directly by returning a `NextResponse`. For more information, see [Producing a Response](https://nextjs.org/docs/advanced-features/middleware#producing-a-response). + #### Why This Error Occurred [Middleware](https://nextjs.org/docs/advanced-features/middleware) can no longer produce a response body as of `v12.2+`. From 637b8bf2acac267ba9201aa29dfd0de933c82ae6 Mon Sep 17 00:00:00 2001 From: Amy Burns Date: Tue, 13 Dec 2022 16:46:57 +0000 Subject: [PATCH 2/4] adding some additional clarifcation --- docs/advanced-features/react-18/switchable-runtime.md | 2 +- docs/basic-features/data-fetching/get-server-side-props.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/advanced-features/react-18/switchable-runtime.md b/docs/advanced-features/react-18/switchable-runtime.md index 0fe779f8bdbe..10b3d8847ff2 100644 --- a/docs/advanced-features/react-18/switchable-runtime.md +++ b/docs/advanced-features/react-18/switchable-runtime.md @@ -36,7 +36,7 @@ export const config = { | Scalability | / | High | Highest | | Security | Normal | High | High | | Latency | Normal | Low | Lowest | -| Code Size | / | 50MB | 1MB | +| Code Size | / | 50 MB | 4 MB | | NPM Packages | All | All | A smaller subset | Next.js' default runtime configuration is good for most use cases, but there are still many reasons to change to one runtime over the other one. diff --git a/docs/basic-features/data-fetching/get-server-side-props.md b/docs/basic-features/data-fetching/get-server-side-props.md index afdac8ad6668..f375b4aa8311 100644 --- a/docs/basic-features/data-fetching/get-server-side-props.md +++ b/docs/basic-features/data-fetching/get-server-side-props.md @@ -47,9 +47,9 @@ Take the following example. An API route is used to fetch some data from a CMS. ### getServerSideProps with Edge API Routes -`getServerSideProps` can be used with both Serverless and Edge Runtimes, and you can set props in both. However, currently in Edge Runtime, you do not have access to the response object. This means that you cannot — for example — add cookies in `getServerSideProps`. To have access to the response object, you should continue to use the Serverless runtime, which is the default runtime. +`getServerSideProps` can be used with both Serverless and Edge Runtimes, and you can set props in both. However, currently in Edge Runtime, you do not have access to the response object. This means that you cannot — for example — add cookies in `getServerSideProps`. To have access to the response object, you should **continue to use the Serverless runtime**, which is the default runtime. -You can set the runtime on a [per-page basis](https://nextjs.org/docs/advanced-features/react-18/switchable-runtime#page-runtime-option) by modifying the `config`, for example: +You can explicitly set the runtime on a [per-page basis](https://nextjs.org/docs/advanced-features/react-18/switchable-runtime#page-runtime-option) by modifying the `config`, for example: ``` export const config = { From 9e8687d37575ac16998f66daaf1f545a077e4578 Mon Sep 17 00:00:00 2001 From: Amy Burns Date: Wed, 14 Dec 2022 10:29:49 +0000 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Rich Haines --- .../data-fetching/incremental-static-regeneration.md | 2 +- errors/returning-response-body-in-middleware.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/basic-features/data-fetching/incremental-static-regeneration.md b/docs/basic-features/data-fetching/incremental-static-regeneration.md index 498a5bdf9365..b7fb3ebc63ec 100644 --- a/docs/basic-features/data-fetching/incremental-static-regeneration.md +++ b/docs/basic-features/data-fetching/incremental-static-regeneration.md @@ -27,7 +27,7 @@ description: 'Learn how to create or update static pages at runtime with Increme Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages. -> Note: the [`experimental-edge` runtime](https://nextjs.org/docs/api-reference/edge-runtime) is currently not compatible with ISR although can leverage `stale-while-revalidate` by setting the `cache-control` header manually. +> Note: The [`experimental-edge` runtime](https://nextjs.org/docs/api-reference/edge-runtime) is currently not compatible with ISR, although can leverage `stale-while-revalidate` by setting the `cache-control` header manually. To use ISR, add the `revalidate` prop to `getStaticProps`: diff --git a/errors/returning-response-body-in-middleware.md b/errors/returning-response-body-in-middleware.md index 57c999039272..dd3ea9a34c6c 100644 --- a/errors/returning-response-body-in-middleware.md +++ b/errors/returning-response-body-in-middleware.md @@ -1,6 +1,6 @@ # Returning response body in Middleware -> Note: In Next.js v13.0.0 you can now respond to middleware directly by returning a `NextResponse`. For more information, see [Producing a Response](https://nextjs.org/docs/advanced-features/middleware#producing-a-response). +> Note: In Next.js v13.0.0 you can now respond to Middleware directly by returning a `NextResponse`. For more information, see [Producing a Response](https://nextjs.org/docs/advanced-features/middleware#producing-a-response). #### Why This Error Occurred From fb45ff51fbe75a72c3231097d29308a2cb663497 Mon Sep 17 00:00:00 2001 From: Amy Burns Date: Wed, 14 Dec 2022 12:30:05 +0000 Subject: [PATCH 4/4] updating the name of the runtime --- docs/basic-features/data-fetching/get-server-side-props.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/basic-features/data-fetching/get-server-side-props.md b/docs/basic-features/data-fetching/get-server-side-props.md index f375b4aa8311..621a85fdc50f 100644 --- a/docs/basic-features/data-fetching/get-server-side-props.md +++ b/docs/basic-features/data-fetching/get-server-side-props.md @@ -47,7 +47,7 @@ Take the following example. An API route is used to fetch some data from a CMS. ### getServerSideProps with Edge API Routes -`getServerSideProps` can be used with both Serverless and Edge Runtimes, and you can set props in both. However, currently in Edge Runtime, you do not have access to the response object. This means that you cannot — for example — add cookies in `getServerSideProps`. To have access to the response object, you should **continue to use the Serverless runtime**, which is the default runtime. +`getServerSideProps` can be used with both Serverless and Edge Runtimes, and you can set props in both. However, currently in Edge Runtime, you do not have access to the response object. This means that you cannot — for example — add cookies in `getServerSideProps`. To have access to the response object, you should **continue to use the Node.js runtime**, which is the default runtime. You can explicitly set the runtime on a [per-page basis](https://nextjs.org/docs/advanced-features/react-18/switchable-runtime#page-runtime-option) by modifying the `config`, for example: