Unverified Commit 27d2fa28 authored by Lee Robinson's avatar Lee Robinson Committed by GitHub

docs: remove Vercel mentions and improve deployment page (#78557)

This PR prunes references to Vercel in the documentation. Some of the
mentions were egregious and unneeded. Others were documenting specific
behavior for how Next.js runs on Vercel, which is better suited for the
Vercel documentation.

It also restructures our deployment documentation to remove any previous
bias toward Vercel. Rather than separating self-hosting (Node.js server,
Docker, static export) into its own section from managed platforms, it
now lists them all together. Vercel is listed under "Adapters",
alongside Netlify, Cloudflare, and AWS Amplify (in alphabetical order).
These are the companies we're working with on the [Deployment Adapters
API](https://github.com/vercel/next.js/discussions/77740), who currently
maintain their own adapters and will eventually migrate to use this new
API. We've [started working
on](https://github.com/vercel/next.js/pull/78166) that API.

For different features in the docs, like ISR or Middleware, this PR also
adds a new feature matrix that shows the different deployment options
and whether this feature is supported. For example, features that
require using the server are not supported with static exports.
Additionally, when there is configuration possible (like changing the
caching behavior of ISR) we link back to our guide which explains these
options in detail.


![image](https://github.com/user-attachments/assets/6dff819b-c46f-4b1a-833c-0827c6ef8735)

This PR also updates the Middleware section of the self-hosting guide to
mention [Node.js runtime
support](https://nextjs.org/blog/next-15-2#nodejs-middleware-experimental).

I've also removed the "Managed Next.js (Vercel)" entry for the docs
sidebar, as it is not necessary and Vercel should not have additional
priority there over other providers.


![image](https://github.com/user-attachments/assets/6d3291b8-f9bd-47e7-a21e-b843c0e1ef0c)


Netlify has confirmed they're okay with the specific feature matrix link
included in the adapters section, and I did my best to include the
Cloudflare and Amplify versions based on their documentation. If any of
the providers want to see changes to those links, please let me know and
I'll open a PR.
parent df3ef84a
...@@ -4,40 +4,77 @@ nav_title: Deploying ...@@ -4,40 +4,77 @@ nav_title: Deploying
description: Learn how to deploy your Next.js application. description: Learn how to deploy your Next.js application.
--- ---
Once you're ready to deploy your Next.js app, you can choose a [managed infrastructure provider](#managed-infrastructure-providers) or [self-host](#self-hosting) your application. Next.js can be deployed as a Node.js server, Docker container, static export, or adapted to run on different platforms.
## Managed infrastructure providers | Deployment Option | Feature Support |
| -------------------------------- | ----------------- |
| [Node.js server](#nodejs-server) | All |
| [Docker container](#docker) | All |
| [Static export](#static-export) | Limited |
| [Adapters](#adapters) | Platform-specific |
A managed platform is a practical option for deploying your Next.js app, as these providers take care of hosting, scaling, and server configuration for you. ## Node.js server
[Vercel](https://vercel.com/docs/frameworks/nextjs?utm_source=next-site&utm_medium=docs&utm_campaign=next-website), the creators and maintainers of Next.js, allows you to deploy your application with **full-feature support** and **zero-configuration**. Next.js can be deployed to any provider that supports Node.js. Ensure your `package.json` has the `"build"` and `"start"` scripts:
- Learn more about [Next.js on Vercel](https://vercel.com/docs/frameworks/nextjs?utm_source=next-site&utm_medium=docs&utm_campaign=next-website). ```json filename="package.json"
- Try Next.js on Vercel by [deploying a template](https://vercel.com/templates/next.js?utm_source=next-site&utm_medium=docs&utm_campaign=next-website). {
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}
```
We also have community maintained deployment templates for: Then, run `npm run build` to build your application and `npm run start` to start the Node.js server. This server supports all Next.js features. If needed, you can also eject to a [custom server](/docs/app/guides/custom-server).
Node.js deployments support all Next.js features. Learn how to [configure them](/docs/app/guides/self-hosting) for your infrastructure.
### Templates
- [Deno](https://github.com/nextjs/deploy-deno)
- [Flightcontrol](https://github.com/nextjs/deploy-flightcontrol) - [Flightcontrol](https://github.com/nextjs/deploy-flightcontrol)
- [Railway](https://github.com/nextjs/deploy-railway) - [Railway](https://github.com/nextjs/deploy-railway)
- [Replit](https://github.com/nextjs/deploy-replit)
## Docker
Next.js can be deployed to any provider that supports [Docker](https://www.docker.com/) containers. This includes container orchestrators like Kubernetes or a cloud provider that runs Docker.
Docker deployments support all Next.js features. Learn how to [configure them](/docs/app/guides/self-hosting) for your infrastructure.
### Templates
- [Docker](https://github.com/vercel/next.js/tree/canary/examples/with-docker)
- [Docker Multi-Environment](https://github.com/vercel/next.js/tree/canary/examples/with-docker-multi-env)
- [DigitalOcean](https://github.com/nextjs/deploy-digitalocean)
- [Fly.io](https://github.com/nextjs/deploy-fly)
- [Google Cloud Run](https://github.com/nextjs/deploy-google-cloud-run)
- [Render](https://github.com/nextjs/deploy-render) - [Render](https://github.com/nextjs/deploy-render)
- [SST](https://github.com/nextjs/deploy-sst) - [SST](https://github.com/nextjs/deploy-sst)
Please refer to each provider's documentation for information on supported Next.js features. ## Static export
## Self-Hosting Next.js enables starting as a static site or [Single-Page Application (SPA)](/docs/app/guides/single-page-applications), then later optionally upgrading to use features that require a server.
Self-hosting may mean you're responsible for provisioning your own servers, managing containers, and scaling. You can self-host Next.js in three different ways: Since Next.js supports [static exports](/docs/app/guides/static-exports), it can be deployed and hosted on any web server that can serve HTML/CSS/JS static assets. This includes tools like AWS S3, Nginx, or Apache.
- [A Node.js server](/docs/app/guides/self-hosting#nodejs-server) Running as a [static export](/docs/app/guides/static-exports) **does not** support Next.js features that require a server. [Learn more](/docs/app/guides/static-exports#unsupported-features).
- [A Docker container](/docs/app/guides/self-hosting#docker-image)
- [A static export](/docs/app/guides/self-hosting#static-html-export)
We have community maintained deployment examples with the following self-hosting providers: ### Templates
- [DigitalOcean](https://github.com/nextjs/deploy-digitalocean)
- [Fly.io](https://github.com/nextjs/deploy-fly)
- [GitHub Pages](https://github.com/nextjs/deploy-github-pages) - [GitHub Pages](https://github.com/nextjs/deploy-github-pages)
- [Google Cloud Run](https://github.com/nextjs/deploy-google-cloud-run)
> **🎥 Watch:** Learn more about self-hosting Next.js → [YouTube (45 minutes)](https://www.youtube.com/watch?v=sIVL4JMqRfc). ## Adapters
Next.js can be adapted to run on different platforms to support their infrastructure capabilities.
Refer to each provider's documentation for information on supported Next.js features:
- [AWS Amplify](https://docs.amplify.aws/nextjs/start/quickstart/nextjs-app-router-client-components)
- [Cloudflare](https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/supported-features)
- [Deno Deploy](https://docs.deno.com/examples/next_tutorial)
- [Netlify](https://docs.netlify.com/frameworks/next-js/overview/#next-js-support-on-netlify)
- [Vercel](https://vercel.com/docs/frameworks/nextjs)
> **Note:** We are working on a [Deployment Adapters API](https://github.com/vercel/next.js/discussions/77740) for all platforms to adopt. After completion, we will add documentation on how to write your own adapters.
...@@ -949,7 +949,7 @@ export async function createSession(id) { ...@@ -949,7 +949,7 @@ export async function createSession(id) {
> **Tips**: > **Tips**:
> >
> - For faster data retrieval, consider using a database like [Vercel Redis](https://vercel.com/docs/storage/vercel-kv). However, you can also keep the session data in your primary database, and combine data requests to reduce the number of queries. > - For faster access, you may consider adding server caching for the lifetime of the session. You can also keep the session data in your primary database, and combine data requests to reduce the number of queries.
> - You may opt to use database sessions for more advanced use cases, such as keeping track of the last time a user logged in, or number of active devices, or give users the ability to log out of all devices. > - You may opt to use database sessions for more advanced use cases, such as keeping track of the last time a user logged in, or number of active devices, or give users the ability to log out of all devices.
After implementing session management, you'll need to add authorization logic to control what users can access and do within your application. Continue to the [Authorization](#authorization) section to learn more. After implementing session management, you'll need to add authorization logic to control what users can access and do within your application. Continue to the [Authorization](#authorization) section to learn more.
......
...@@ -11,7 +11,6 @@ Next.js includes its own server with `next start` by default. If you have an exi ...@@ -11,7 +11,6 @@ Next.js includes its own server with `next start` by default. If you have an exi
> **Good to know**: > **Good to know**:
> >
> - Before deciding to use a custom server, keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like **[Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization).** > - Before deciding to use a custom server, keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like **[Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization).**
> - A custom server **cannot** be deployed on [Vercel](https://vercel.com/frameworks/nextjs).
> - When using standalone output mode, it does not trace custom server files. This mode outputs a separate minimal `server.js` file, instead. These cannot be used together. > - When using standalone output mode, it does not trace custom server files. This mode outputs a separate minimal `server.js` file, instead. These cannot be used together.
Take a look at the [following example](https://github.com/vercel/next.js/tree/canary/examples/custom-server) of a custom server: Take a look at the [following example](https://github.com/vercel/next.js/tree/canary/examples/custom-server) of a custom server:
......
...@@ -230,20 +230,6 @@ This allows you to use a singular Docker image that can be promoted through mult ...@@ -230,20 +230,6 @@ This allows you to use a singular Docker image that can be promoted through mult
- You can run code on server startup using the [`register` function](/docs/app/guides/instrumentation). - You can run code on server startup using the [`register` function](/docs/app/guides/instrumentation).
- We do not recommend using the [`runtimeConfig`](/docs/pages/api-reference/config/next-config-js/runtime-configuration) option, as this does not work with the standalone output mode. Instead, we recommend [incrementally adopting](/docs/app/guides/migrating/app-router-migration) the App Router if you need this feature. - We do not recommend using the [`runtimeConfig`](/docs/pages/api-reference/config/next-config-js/runtime-configuration) option, as this does not work with the standalone output mode. Instead, we recommend [incrementally adopting](/docs/app/guides/migrating/app-router-migration) the App Router if you need this feature.
## Environment Variables on Vercel
When deploying your Next.js application to [Vercel](https://vercel.com), Environment Variables can be configured [in the Project Settings](https://vercel.com/docs/projects/environment-variables?utm_medium=docs&utm_source=next-site&utm_campaign=next-website).
All types of Environment Variables should be configured there. Even Environment Variables used in Development – which can be [downloaded onto your local device](https://vercel.com/docs/concepts/projects/environment-variables#development-environment-variables?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) afterwards.
If you've configured [Development Environment Variables](https://vercel.com/docs/concepts/projects/environment-variables#development-environment-variables?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) you can pull them into a `.env.local` for usage on your local machine using the following command:
```bash filename="Terminal"
vercel env pull
```
> **Good to know**: When deploying your Next.js application to [Vercel](https://vercel.com), your environment variables in `.env*` files will not be made available to Edge Runtime, unless their name are prefixed with `NEXT_PUBLIC_`. We strongly recommend managing your environment variables in [Project Settings](https://vercel.com/docs/projects/environment-variables?utm_medium=docs&utm_source=next-site&utm_campaign=next-website) instead, from where all environment variables are available.
## Test Environment Variables ## Test Environment Variables
Apart from `development` and `production` environments, there is a 3rd option available: `test`. In the same way you can set defaults for development or production environments, you can do the same with a `.env.test` file for the `testing` environment (though this one is not as common as the previous two). Next.js will not load environment variables from `.env.development` or `.env.production` in the `testing` environment. Apart from `development` and `production` environments, there is a 3rd option available: `test`. In the same way you can set defaults for development or production environments, you can do the same with a `.env.test` file for the `testing` environment (though this one is not as common as the previous two). Next.js will not load environment variables from `.env.development` or `.env.production` in the `testing` environment.
......
...@@ -57,7 +57,7 @@ description: Learn how to implement common UI patterns and use cases using Next. ...@@ -57,7 +57,7 @@ description: Learn how to implement common UI patterns and use cases using Next.
### Deployment ### Deployment
- [Creating a Dockerfile](/docs/app/guides/self-hosting#docker-image) - [Creating a Dockerfile](/docs/app/getting-started/deploying#docker)
- [Creating a static export (SPA)](/docs/app/guides/static-exports) - [Creating a static export (SPA)](/docs/app/guides/static-exports)
- [Configuring caching when self-hosting](/docs/app/guides/self-hosting#configuring-caching) - [Configuring caching when self-hosting](/docs/app/guides/self-hosting#configuring-caching)
- [Configuring Image Optimization when self-hosting](/docs/app/guides/self-hosting#image-optimization) - [Configuring Image Optimization when self-hosting](/docs/app/guides/self-hosting#image-optimization)
...@@ -117,8 +117,6 @@ The Next.js applications that make up the different zones can live in any reposi ...@@ -117,8 +117,6 @@ The Next.js applications that make up the different zones can live in any reposi
Since the pages in different zones may be released at different times, feature flags can be useful for enabling or disabling features in unison across the different zones. Since the pages in different zones may be released at different times, feature flags can be useful for enabling or disabling features in unison across the different zones.
For [Next.js on Vercel](https://vercel.com?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) applications, you can use a [monorepo](https://vercel.com/blog/monorepos-are-changing-how-teams-build-software?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) to deploy all affected zones with a single `git push`.
<AppOnly> <AppOnly>
## Server Actions ## Server Actions
......
...@@ -6,7 +6,7 @@ description: Recommendations to ensure the best performance and user experience ...@@ -6,7 +6,7 @@ description: Recommendations to ensure the best performance and user experience
Before taking your Next.js application to production, there are some optimizations and patterns you should consider implementing for the best user experience, performance, and security. Before taking your Next.js application to production, there are some optimizations and patterns you should consider implementing for the best user experience, performance, and security.
This page provides best practices that you can use as a reference when [building your application](#during-development), [before going to production](#before-going-to-production), and [after deployment](#after-deployment) - as well as the [automatic Next.js optimizations](#automatic-optimizations) you should be aware of. This page provides best practices that you can use as a reference when [building your application](#during-development) and [before going to production](#before-going-to-production), as well as the [automatic Next.js optimizations](#automatic-optimizations) you should be aware of.
## Automatic optimizations ## Automatic optimizations
...@@ -148,19 +148,3 @@ Additionally, the following tools can help you understand the impact of adding n ...@@ -148,19 +148,3 @@ Additionally, the following tools can help you understand the impact of adding n
- [Package Phobia](https://packagephobia.com/) - [Package Phobia](https://packagephobia.com/)
- [Bundle Phobia](https://bundlephobia.com/) - [Bundle Phobia](https://bundlephobia.com/)
- [bundlejs](https://bundlejs.com/) - [bundlejs](https://bundlejs.com/)
## After deployment
Depending on where you deploy your application, you might have access to additional tools and integrations to help you monitor and improve your application's performance.
For Vercel deployments, we recommend the following:
- **[Analytics](https://vercel.com/analytics?utm_source=next-site&utm_campaign=nextjs-docs&utm_medium=docs):** A built-in analytics dashboard to help you understand your application's traffic, including the number of unique visitors, page views, and more.
- **[Speed Insights](https://vercel.com/docs/speed-insights?utm_source=next-site&utm_campaign=nextjs-docs&utm_medium=docs):** Real-world performance insights based on visitor data, offering a practical view of how your website is performing in the field.
- **[Logging](https://vercel.com/docs/observability/runtime-logs?utm_source=next-site&utm_campaign=nextjs-docs&utm_medium=docs):** Runtime and Activity logs to help you debug issues and monitor your application in production. Alternatively, see the [integrations page](https://vercel.com/integrations?utm_source=next-site&utm_campaign=nextjs-docs&utm_medium=docs) for a list of third-party tools and services.
> **Good to know:**
>
> To get a comprehensive understanding of the best practices for production deployments on Vercel, including detailed strategies for improving website performance, refer to the [Vercel Production Checklist](https://vercel.com/docs/production-checklist?utm_source=next-site&utm_campaign=nextjs-docs&utm_medium=docs).
Following these recommendations will help you build a faster, more reliable, and secure application for your users.
This diff is collapsed.
...@@ -182,3 +182,14 @@ For more Suspense examples and use cases, please see the [React Documentation](h ...@@ -182,3 +182,14 @@ For more Suspense examples and use cases, please see the [React Documentation](h
When streaming, a `200` status code will be returned to signal that the request was successful. When streaming, a `200` status code will be returned to signal that the request was successful.
The server can still communicate errors or issues to the client within the streamed content itself, for example, when using [`redirect`](/docs/app/api-reference/functions/redirect) or [`notFound`](/docs/app/api-reference/functions/not-found). Since the response headers have already been sent to the client, the status code of the response cannot be updated. This does not affect SEO. The server can still communicate errors or issues to the client within the streamed content itself, for example, when using [`redirect`](/docs/app/api-reference/functions/redirect) or [`notFound`](/docs/app/api-reference/functions/not-found). Since the response headers have already been sent to the client, the status code of the response cannot be updated. This does not affect SEO.
## Platform Support
| Deployment Option | Supported |
| ------------------------------------------------------------------- | ----------------- |
| [Node.js server](/docs/app/getting-started/deploying#nodejs-server) | Yes |
| [Docker container](/docs/app/getting-started/deploying#docker) | Yes |
| [Static export](/docs/app/getting-started/deploying#static-export) | No |
| [Adapters](/docs/app/getting-started/deploying#adapters) | Platform-specific |
Learn how to [configure streaming](/docs/app/guides/self-hosting#streaming-and-suspense) when self-hosting Next.js.
...@@ -375,7 +375,7 @@ Consider the following data structure: ...@@ -375,7 +375,7 @@ Consider the following data structure:
} }
``` ```
In [Middleware](/docs/app/building-your-application/routing/middleware), you can read from a database such as Vercel's [Edge Config](https://vercel.com/docs/storage/edge-config/get-started?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) or [Redis](https://vercel.com/docs/storage/vercel-kv?utm_source=next-site&utm_medium=docs&utm_campaign=next-website), and redirect the user based on the incoming request: In [Middleware](/docs/app/building-your-application/routing/middleware), you can read from a database such as Vercel's [Edge Config](https://vercel.com/docs/edge-config/get-started) or [Redis](https://vercel.com/docs/redis), and redirect the user based on the incoming request:
```ts filename="middleware.ts" switcher ```ts filename="middleware.ts" switcher
import { NextResponse, NextRequest } from 'next/server' import { NextResponse, NextRequest } from 'next/server'
...@@ -424,7 +424,7 @@ export async function middleware(request) { ...@@ -424,7 +424,7 @@ export async function middleware(request) {
Reading a large dataset for every incoming request can be slow and expensive. There are two ways you can optimize data lookup performance: Reading a large dataset for every incoming request can be slow and expensive. There are two ways you can optimize data lookup performance:
- Use a database that is optimized for fast reads, such as [Vercel Edge Config](https://vercel.com/docs/storage/edge-config/get-started?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) or [Redis](https://vercel.com/docs/storage/vercel-kv?utm_source=next-site&utm_medium=docs&utm_campaign=next-website). - Use a database that is optimized for fast reads
- Use a data lookup strategy such as a [Bloom filter](https://en.wikipedia.org/wiki/Bloom_filter) to efficiently check if a redirect exists **before** reading the larger redirects file or database. - Use a data lookup strategy such as a [Bloom filter](https://en.wikipedia.org/wiki/Bloom_filter) to efficiently check if a redirect exists **before** reading the larger redirects file or database.
Considering the previous example, you can import a generated bloom filter file into Middleware, then, check if the incoming request pathname exists in the bloom filter. Considering the previous example, you can import a generated bloom filter file into Middleware, then, check if the incoming request pathname exists in the bloom filter.
......
...@@ -638,6 +638,17 @@ export const config = { ...@@ -638,6 +638,17 @@ export const config = {
> **Note**: This feature is not yet recommended for production use. Therefore, Next.js will throw an error unless you are using the next@canary release instead of the stable release. > **Note**: This feature is not yet recommended for production use. Therefore, Next.js will throw an error unless you are using the next@canary release instead of the stable release.
## Platform Support
| Deployment Option | Supported |
| ------------------------------------------------------------------- | ----------------- |
| [Node.js server](/docs/app/getting-started/deploying#nodejs-server) | Yes |
| [Docker container](/docs/app/getting-started/deploying#docker) | Yes |
| [Static export](/docs/app/getting-started/deploying#static-export) | No |
| [Adapters](/docs/app/getting-started/deploying#adapters) | Platform-specific |
Learn how to [configure Middleware](/docs/app/guides/self-hosting#middleware) when self-hosting Next.js.
## Version History ## Version History
| Version | Changes | | Version | Changes |
......
...@@ -539,10 +539,6 @@ export async function getStaticProps({ params }) { ...@@ -539,10 +539,6 @@ export async function getStaticProps({ params }) {
### Customizing the cache location ### Customizing the cache location
Caching and revalidating pages (with Incremental Static Regeneration) use the same shared cache. When [deploying to Vercel](https://vercel.com/docs/incremental-static-regeneration?utm_source=next-site&utm_medium=docs&utm_campaign=next-website), the ISR cache is automatically persisted to durable storage.
When self-hosting, the ISR cache is stored to the filesystem (on disk) on your Next.js server. This works automatically when self-hosting using both the Pages and App Router.
You can configure the Next.js cache location if you want to persist cached pages and data to durable storage, or share the cache across multiple containers or instances of your Next.js application. [Learn more](/docs/app/guides/self-hosting#caching-and-isr). You can configure the Next.js cache location if you want to persist cached pages and data to durable storage, or share the cache across multiple containers or instances of your Next.js application. [Learn more](/docs/app/guides/self-hosting#caching-and-isr).
## Troubleshooting ## Troubleshooting
...@@ -593,6 +589,17 @@ This will make the Next.js server console log ISR cache hits and misses. You can ...@@ -593,6 +589,17 @@ This will make the Next.js server console log ISR cache hits and misses. You can
</PagesOnly> </PagesOnly>
## Platform Support
| Deployment Option | Supported |
| ------------------------------------------------------------------- | ----------------- |
| [Node.js server](/docs/app/getting-started/deploying#nodejs-server) | Yes |
| [Docker container](/docs/app/getting-started/deploying#docker) | Yes |
| [Static export](/docs/app/getting-started/deploying#static-export) | No |
| [Adapters](/docs/app/getting-started/deploying#adapters) | Platform-specific |
Learn how to [configure ISR](/docs/app/guides/self-hosting#caching-and-isr) when self-hosting Next.js.
## Version history ## Version history
| Version | Changes | | Version | Changes |
......
...@@ -219,3 +219,16 @@ export async function Table({ searchParams }) { ...@@ -219,3 +219,16 @@ export async function Table({ searchParams }) {
return '...' return '...'
} }
``` ```
## Platform Support
> **Note:** Partial Prerendering is an **experimental** feature only available on canary and is subject to change. It is not ready for production use.
| Deployment Option | Supported |
| ------------------------------------------------------------------- | ----------------- |
| [Node.js server](/docs/app/getting-started/deploying#nodejs-server) | Yes |
| [Docker container](/docs/app/getting-started/deploying#docker) | Yes |
| [Static export](/docs/app/getting-started/deploying#static-export) | No |
| [Adapters](/docs/app/getting-started/deploying#adapters) | Platform-specific |
Learn how to [configure PPR](/docs/app/guides/self-hosting#partial-prerendering) when self-hosting Next.js.
...@@ -356,3 +356,20 @@ export default function ClientComponent({ action }) { ...@@ -356,3 +356,20 @@ export default function ClientComponent({ action }) {
return <button onClick={action}>Update</button> return <button onClick={action}>Update</button>
} }
``` ```
## Platform Support
| Deployment Option | Supported |
| ------------------------------------------------------------------- | ----------------- |
| [Node.js server](/docs/app/getting-started/deploying#nodejs-server) | Yes |
| [Docker container](/docs/app/getting-started/deploying#docker) | Yes |
| [Static export](/docs/app/getting-started/deploying#static-export) | No |
| [Adapters](/docs/app/getting-started/deploying#adapters) | Platform-specific |
Learn how to [configure caching](/docs/app/guides/self-hosting#caching-and-isr) when self-hosting Next.js.
## Version History
| Version | Changes |
| --------- | ------------------------------------------------------- |
| `v15.0.0` | `"use cache"` is introduced as an experimental feature. |
...@@ -43,8 +43,3 @@ The folder is also useful for `robots.txt`, `favicon.ico`, Google Site Verificat ...@@ -43,8 +43,3 @@ The folder is also useful for `robots.txt`, `favicon.ico`, Google Site Verificat
For static metadata files, such as `robots.txt`, `favicon.ico`, etc, you should use [special metadata files](/docs/app/api-reference/file-conventions/metadata) inside the `app` folder. For static metadata files, such as `robots.txt`, `favicon.ico`, etc, you should use [special metadata files](/docs/app/api-reference/file-conventions/metadata) inside the `app` folder.
</AppOnly> </AppOnly>
> Good to know:
>
> - The directory must be named `public`. The name cannot be changed and it's the only directory used to serve static assets.
> - Only assets that are in the `public` directory at [build time](/docs/app/api-reference/cli/next#next-build-options) will be served by Next.js. Files added at request time won't be available. We recommend using a third-party service like [Vercel Blob](https://vercel.com/docs/storage/vercel-blob?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) for persistent file storage.
...@@ -201,7 +201,6 @@ Support for `preferredRegion`, and regions supported, is dependent on your deplo ...@@ -201,7 +201,6 @@ Support for `preferredRegion`, and regions supported, is dependent on your deplo
By default, Next.js does not limit the execution of server-side logic (rendering a page or handling an API). By default, Next.js does not limit the execution of server-side logic (rendering a page or handling an API).
Deployment platforms can use `maxDuration` from the Next.js build output to add specific execution limits. Deployment platforms can use `maxDuration` from the Next.js build output to add specific execution limits.
For example, on [Vercel](https://vercel.com/docs/functions/serverless-functions/runtimes#max-duration).
**Note**: This setting requires Next.js `13.4.10` or higher. **Note**: This setting requires Next.js `13.4.10` or higher.
......
...@@ -55,15 +55,6 @@ export default function Layout({ children }) { ...@@ -55,15 +55,6 @@ export default function Layout({ children }) {
- You can use React `cache` to deduplicate functions called inside `after`. - You can use React `cache` to deduplicate functions called inside `after`.
- `after` can be nested inside other `after` calls, for example, you can create utility functions that wrap `after` calls to add additional functionality. - `after` can be nested inside other `after` calls, for example, you can create utility functions that wrap `after` calls to add additional functionality.
## Alternatives
The use case for `after` is to process secondary tasks without blocking the primary response. It's similar to using the platform's [`waitUntil()`](https://vercel.com/docs/functions/functions-api-reference) or removing `await` from a promise, but with the following differences:
- **`waitUntil()`**: accepts a promise and enqueues a task to be executed during the lifecycle of the request, whereas `after` accepts a callback that will be executed **after** the response is finished.
- **Removing `await`**: starts executing during the response, which uses resources. It's also not reliable in serverless environments as the function stops computation immediately after the response is sent, potentially interrupting the task.
We recommend using `after` as it has been designed to consider other Next.js APIs and contexts.
## Examples ## Examples
### With request APIs ### With request APIs
...@@ -122,6 +113,69 @@ export async function POST(request) { ...@@ -122,6 +113,69 @@ export async function POST(request) {
However, you cannot use these request APIs inside `after` in [Server Components](/docs/app/building-your-application/rendering/server-components). This is because Next.js needs to know which part of the tree access the request APIs to support [Partial Prerendering](/docs/app/building-your-application/rendering/partial-prerendering), but `after` runs after React's rendering lifecycle. However, you cannot use these request APIs inside `after` in [Server Components](/docs/app/building-your-application/rendering/server-components). This is because Next.js needs to know which part of the tree access the request APIs to support [Partial Prerendering](/docs/app/building-your-application/rendering/partial-prerendering), but `after` runs after React's rendering lifecycle.
## Platform Support
| Deployment Option | Supported |
| ------------------------------------------------------------------- | ----------------- |
| [Node.js server](/docs/app/getting-started/deploying#nodejs-server) | Yes |
| [Docker container](/docs/app/getting-started/deploying#docker) | Yes |
| [Static export](/docs/app/getting-started/deploying#static-export) | No |
| [Adapters](/docs/app/getting-started/deploying#adapters) | Platform-specific |
Learn how to [configure `after`](/docs/app/guides/self-hosting#after) when self-hosting Next.js.
<details id="after-serverless">
<summary>Reference: supporting `after` for serverless platforms</summary>
Using `after` in a serverless context requires waiting for asynchronous tasks to finish after the response has been sent. In Next.js and Vercel, this is achieved using a primitive called `waitUntil(promise)`, which extends the lifetime of a serverless invocation until all promises passed to [`waitUntil`](https://vercel.com/docs/functions/functions-api-reference#waituntil) have settled.
If you want your users to be able to run `after`, you will have to provide your implementation of `waitUntil` that behaves in an analogous way.
When `after` is called, Next.js will access `waitUntil` like this:
```jsx
const RequestContext = globalThis[Symbol.for('@next/request-context')]
const contextValue = RequestContext?.get()
const waitUntil = contextValue?.waitUntil
```
Which means that `globalThis[Symbol.for('@next/request-context')]` is expected to contain an object like this:
```tsx
type NextRequestContext = {
get(): NextRequestContextValue | undefined
}
type NextRequestContextValue = {
waitUntil?: (promise: Promise<any>) => void
}
```
Here is an example of the implementation.
```tsx
import { AsyncLocalStorage } from 'node:async_hooks'
const RequestContextStorage = new AsyncLocalStorage<NextRequestContextValue>()
// Define and inject the accessor that next.js will use
const RequestContext: NextRequestContext = {
get() {
return RequestContextStorage.getStore()
},
}
globalThis[Symbol.for('@next/request-context')] = RequestContext
const handler = (req, res) => {
const contextValue = { waitUntil: YOUR_WAITUNTIL }
// Provide the value
return RequestContextStorage.run(contextValue, () => nextJsHandler(req, res))
}
```
</details>
## Version History
| Version History | Description | | Version History | Description |
| --------------- | ---------------------------- | | --------------- | ---------------------------- |
| `v15.1.0` | `after` became stable. | | `v15.1.0` | `after` became stable. |
......
...@@ -391,7 +391,6 @@ export const metadata = { ...@@ -391,7 +391,6 @@ export const metadata = {
- `metadataBase` allows URL-based `metadata` fields defined in the **current route segment and below** to use a **relative path** instead of an otherwise required absolute URL. - `metadataBase` allows URL-based `metadata` fields defined in the **current route segment and below** to use a **relative path** instead of an otherwise required absolute URL.
- The field's relative path will be composed with `metadataBase` to form a fully qualified URL. - The field's relative path will be composed with `metadataBase` to form a fully qualified URL.
- If not configured, `metadataBase` is **automatically populated** with a [default value](#default-value).
```jsx filename="layout.js | page.js" ```jsx filename="layout.js | page.js"
export const metadata = { export const metadata = {
...@@ -425,19 +424,6 @@ export const metadata = { ...@@ -425,19 +424,6 @@ export const metadata = {
> - Using a relative path in a URL-based `metadata` field without configuring a `metadataBase` will cause a build error. > - Using a relative path in a URL-based `metadata` field without configuring a `metadataBase` will cause a build error.
> - Next.js will normalize duplicate slashes between `metadataBase` (e.g. `https://acme.com/`) and a relative field (e.g. `/path`) to a single slash (e.g. `https://acme.com/path`) > - Next.js will normalize duplicate slashes between `metadataBase` (e.g. `https://acme.com/`) and a relative field (e.g. `/path`) to a single slash (e.g. `https://acme.com/path`)
#### Default value
If not configured, `metadataBase` has a **default value**.
> On Vercel:
>
> - For production deployments, `VERCEL_PROJECT_PRODUCTION_URL` will be used.
> - For preview deployments, `VERCEL_BRANCH_URL` will take priority, and fallback to `VERCEL_URL` if it's not present.
>
> If these values are present they will be used as the **default value** of `metadataBase`, otherwise it falls back to `http://localhost:${process.env.PORT || 3000}`. This allows Open Graph images to work on both local build and Vercel preview and production deployments. When overriding the default, we recommend using environment variables to compute the URL. This allows configuring a URL for local development, staging, and production environments.
>
> See more details about these environment variables in the [System Environment Variables](https://vercel.com/docs/concepts/projects/environment-variables/system-environment-variables) docs.
#### URL Composition #### URL Composition
URL composition favors developer intent over default directory traversal semantics. URL composition favors developer intent over default directory traversal semantics.
......
...@@ -194,11 +194,6 @@ These metrics work in all browsers that support the [User Timing API](https://ca ...@@ -194,11 +194,6 @@ These metrics work in all browsers that support the [User Timing API](https://ca
</PagesOnly> </PagesOnly>
## Usage on Vercel
[Vercel Speed Insights](https://vercel.com/docs/speed-insights/quickstart) does not `useReportWebVitals`, but `@vercel/speed-insights` package instead.
`useReportWebVitals` hook is useful in local development, or if you're using a different service for collecting Web Vitals.
## Sending results to external systems ## Sending results to external systems
You can send results to any endpoint to measure and track You can send results to any endpoint to measure and track
......
...@@ -7,10 +7,7 @@ description: Next.js provides gzip compression to compress rendered content and ...@@ -7,10 +7,7 @@ description: Next.js provides gzip compression to compress rendered content and
By default, Next.js uses `gzip` to compress rendered content and static files when using `next start` or a custom server. This is an optimization for applications that do not have compression configured. If compression is _already_ configured in your application via a custom server, Next.js will not add compression. By default, Next.js uses `gzip` to compress rendered content and static files when using `next start` or a custom server. This is an optimization for applications that do not have compression configured. If compression is _already_ configured in your application via a custom server, Next.js will not add compression.
> **Good to know:** You can check if compression is enabled and which algorithm is used by looking at the [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) (browser accepted options) and [`Content-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) (currently used) headers in the response.
>
> - When hosting your application on [Vercel](https://vercel.com/docs/edge-network/compression), compression uses `brotli` first, then `gzip`.
> - You can check if compression is enabled and which algorithm is used by looking at the [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) (browser accepted options) and [`Content-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) (currently used) headers in the response.
## Disabling compression ## Disabling compression
...@@ -22,14 +19,4 @@ module.exports = { ...@@ -22,14 +19,4 @@ module.exports = {
} }
``` ```
We do not recommend disabling compression unless you have compression configured on your server, as compression reduces bandwidth usage and improves the performance of your application. We **do not recommend disabling compression** unless you have compression configured on your server, as compression reduces bandwidth usage and improves the performance of your application. For example, you're using [nginx](https://nginx.org/) and want to switch to `brotli`, set the `compress` option to `false` to allow nginx to handle compression.
## Changing the compression algorithm
To change your compression algorithm, you will need to configure your custom server and set the `compress` option to `false` in your `next.config.js` file.
For example, you're using [nginx](https://nginx.org/) and want to switch to `brotli`, set the `compress` option to `false` to allow nginx to handle compression.
> **Good to know:**
>
> - For Next.js applications on Vercel, compression is handled by the Vercel's Edge Network and not Next.js. See the [Vercel documentation](https://vercel.com/docs/edge-network/compression) for more information.
...@@ -518,8 +518,6 @@ async headers() { ...@@ -518,8 +518,6 @@ async headers() {
[This header](https://developer.mozilla.org/docs/Web/HTTP/Headers/Strict-Transport-Security) informs browsers it should only be accessed using HTTPS, instead of using HTTP. Using the configuration below, all present and future subdomains will use HTTPS for a `max-age` of 2 years. This blocks access to pages or subdomains that can only be served over HTTP. [This header](https://developer.mozilla.org/docs/Web/HTTP/Headers/Strict-Transport-Security) informs browsers it should only be accessed using HTTPS, instead of using HTTP. Using the configuration below, all present and future subdomains will use HTTPS for a `max-age` of 2 years. This blocks access to pages or subdomains that can only be served over HTTP.
If you're deploying to [Vercel](https://vercel.com/docs/concepts/edge-network/headers#strict-transport-security?utm_source=next-site&utm_medium=docs&utm_campaign=next-website), this header is not necessary as it's automatically added to all deployments unless you declare `headers` in your `next.config.js`.
```js ```js
{ {
key: 'Strict-Transport-Security', key: 'Strict-Transport-Security',
......
...@@ -4,10 +4,6 @@ nav_title: cacheHandler ...@@ -4,10 +4,6 @@ nav_title: cacheHandler
description: Configure the Next.js cache used for storing and revalidating data to use any external service like Redis, Memcached, or others. description: Configure the Next.js cache used for storing and revalidating data to use any external service like Redis, Memcached, or others.
--- ---
Caching and revalidating pages (with Incremental Static Regeneration) use the same shared cache. When [deploying to Vercel](https://vercel.com/docs/incremental-static-regeneration?utm_source=next-site&utm_medium=docs&utm_campaign=next-website), the ISR cache is automatically persisted to durable storage.
When self-hosting, the ISR cache is stored to the filesystem (on disk) on your Next.js server. This works automatically when self-hosting using both the Pages and App Router.
You can configure the Next.js cache location if you want to persist cached pages and data to durable storage, or share the cache across multiple containers or instances of your Next.js application. You can configure the Next.js cache location if you want to persist cached pages and data to durable storage, or share the cache across multiple containers or instances of your Next.js application.
```js filename="next.config.js" ```js filename="next.config.js"
...@@ -17,11 +13,11 @@ module.exports = { ...@@ -17,11 +13,11 @@ module.exports = {
} }
``` ```
View an example of a [custom cache handler](/docs/app/guides/self-hosting#configuring-caching) and learn more about implementation. View an example of a [custom cache handler](/docs/app/guides/self-hosting#configuring-caching) and learn more about the implementation.
## API Reference ## API Reference
The cache handler can implement the following methods: `get`, `set`, and `revalidateTag`. The cache handler can implement the following methods: `get`, `set`, `revalidateTag`, and `resetRequestCache`.
### `get()` ### `get()`
...@@ -49,10 +45,27 @@ Returns `Promise<void>`. ...@@ -49,10 +45,27 @@ Returns `Promise<void>`.
Returns `Promise<void>`. Learn more about [revalidating data](/docs/app/building-your-application/data-fetching/incremental-static-regeneration) or the [`revalidateTag()`](/docs/app/api-reference/functions/revalidateTag) function. Returns `Promise<void>`. Learn more about [revalidating data](/docs/app/building-your-application/data-fetching/incremental-static-regeneration) or the [`revalidateTag()`](/docs/app/api-reference/functions/revalidateTag) function.
### `resetRequestCache()`
This method resets the temporary in-memory cache for a single request before the next request.
Returns `void`.
**Good to know:** **Good to know:**
- `revalidatePath` is a convenience layer on top of cache tags. Calling `revalidatePath` will call your `revalidateTag` function, which you can then choose if you want to tag cache keys based on the path. - `revalidatePath` is a convenience layer on top of cache tags. Calling `revalidatePath` will call your `revalidateTag` function, which you can then choose if you want to tag cache keys based on the path.
## Platform Support
| Deployment Option | Supported |
| ------------------------------------------------------------------- | ----------------- |
| [Node.js server](/docs/app/getting-started/deploying#nodejs-server) | Yes |
| [Docker container](/docs/app/getting-started/deploying#docker) | Yes |
| [Static export](/docs/app/getting-started/deploying#static-export) | No |
| [Adapters](/docs/app/getting-started/deploying#adapters) | Platform-specific |
Learn how to [configure ISR](/docs/app/guides/self-hosting#caching-and-isr) when self-hosting Next.js.
## Version History ## Version History
| Version | Changes | | Version | Changes |
......
...@@ -93,8 +93,6 @@ module.exports = { ...@@ -93,8 +93,6 @@ module.exports = {
**Note:** The key of `outputFileTracingIncludes`/`outputFileTracingExcludes` is a [glob](https://www.npmjs.com/package/picomatch#basic-globbing), so special characters need to be escaped. **Note:** The key of `outputFileTracingIncludes`/`outputFileTracingExcludes` is a [glob](https://www.npmjs.com/package/picomatch#basic-globbing), so special characters need to be escaped.
- Currently, Next.js does not do anything with the emitted `.nft.json` files. The files must be read by your deployment platform, for example [Vercel](https://vercel.com), to create a minimal deployment. In a future release, a new command is planned to utilize these `.nft.json` files.
## Experimental `turbotrace` ## Experimental `turbotrace`
Tracing dependencies can be slow because it requires very complex computations and analysis. We created `turbotrace` in Rust as a faster and smarter alternative to the JavaScript implementation. Tracing dependencies can be slow because it requires very complex computations and analysis. We created `turbotrace` in Rust as a faster and smarter alternative to the JavaScript implementation.
......
...@@ -217,8 +217,6 @@ next dev --experimental-https --experimental-https-key ./certificates/localhost- ...@@ -217,8 +217,6 @@ next dev --experimental-https --experimental-https-key ./certificates/localhost-
`next dev --experimental-https` is only intended for development and creates a locally trusted certificate with [`mkcert`](https://github.com/FiloSottile/mkcert). In production, use properly issued certificates from trusted authorities. `next dev --experimental-https` is only intended for development and creates a locally trusted certificate with [`mkcert`](https://github.com/FiloSottile/mkcert). In production, use properly issued certificates from trusted authorities.
> **Good to know**: When deploying to Vercel, HTTPS is [automatically configured](https://vercel.com/docs/security/encryption) for your Next.js application.
### Configuring a timeout for downstream proxies ### Configuring a timeout for downstream proxies
When deploying Next.js behind a downstream proxy (e.g. a load-balancer like AWS ELB/ALB), it's important to configure Next's underlying HTTP server with [keep-alive timeouts](https://nodejs.org/api/http.html#http_server_keepalivetimeout) that are _larger_ than the downstream proxy's timeouts. Otherwise, once a keep-alive timeout is reached for a given TCP connection, Node.js will immediately terminate that connection without notifying the downstream proxy. This results in a proxy error whenever it attempts to reuse a connection that Node.js has already terminated. When deploying Next.js behind a downstream proxy (e.g. a load-balancer like AWS ELB/ALB), it's important to configure Next's underlying HTTP server with [keep-alive timeouts](https://nodejs.org/api/http.html#http_server_keepalivetimeout) that are _larger_ than the downstream proxy's timeouts. Otherwise, once a keep-alive timeout is reached for a given TCP connection, Node.js will immediately terminate that connection without notifying the downstream proxy. This results in a proxy error whenever it attempts to reuse a connection that Node.js has already terminated.
......
...@@ -24,14 +24,6 @@ bun add next@9 ...@@ -24,14 +24,6 @@ bun add next@9
> **Good to know:** If you are using TypeScript, ensure you also upgrade `@types/react` and `@types/react-dom` to their corresponding versions. > **Good to know:** If you are using TypeScript, ensure you also upgrade `@types/react` and `@types/react-dom` to their corresponding versions.
## Production Deployment on Vercel
If you previously configured `routes` in your `vercel.json` file for dynamic routes, these rules can be removed when leveraging Next.js 9's new [Dynamic Routing feature](/docs/pages/building-your-application/routing/dynamic-routes).
Next.js 9's dynamic routes are **automatically configured on [Vercel](https://vercel.com/)** and do not require any `vercel.json` customization.
You can read more about [Dynamic Routing here](/docs/pages/building-your-application/routing/dynamic-routes).
## Check your Custom App File (`pages/_app.js`) ## Check your Custom App File (`pages/_app.js`)
If you previously copied the [Custom `<App>`](/docs/pages/building-your-application/routing/custom-app) example, you may be able to remove your `getInitialProps`. If you previously copied the [Custom `<App>`](/docs/pages/building-your-application/routing/custom-app) example, you may be able to remove your `getInitialProps`.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment