mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
docs: Move pages from Config section into guides (#78496)
This commit is contained in:
Delba de Oliveira
@@ -31,22 +31,22 @@ Top-level folders are used to organize your application's code and static assets
|
||||
|
||||
Top-level files are used to configure your application, manage dependencies, run middleware, integrate monitoring tools, and define environment variables.
|
||||
|
||||
| | |
|
||||
| ------------------------------------------------------------------------------------------- | --------------------------------------- |
|
||||
| **Next.js** | |
|
||||
| [`next.config.js`](/docs/app/api-reference/config/next-config-js) | Configuration file for Next.js |
|
||||
| [`package.json`](/docs/app/getting-started/installation#manual-installation) | Project dependencies and scripts |
|
||||
| [`instrumentation.ts`](/docs/app/building-your-application/optimizing/instrumentation) | OpenTelemetry and Instrumentation file |
|
||||
| [`middleware.ts`](/docs/app/building-your-application/routing/middleware) | Next.js request middleware |
|
||||
| [`.env`](/docs/app/building-your-application/configuring/environment-variables) | Environment variables |
|
||||
| [`.env.local`](/docs/app/building-your-application/configuring/environment-variables) | Local environment variables |
|
||||
| [`.env.production`](/docs/app/building-your-application/configuring/environment-variables) | Production environment variables |
|
||||
| [`.env.development`](/docs/app/building-your-application/configuring/environment-variables) | Development environment variables |
|
||||
| [`.eslintrc.json`](/docs/app/api-reference/config/eslint) | Configuration file for ESLint |
|
||||
| `.gitignore` | Git files and folders to ignore |
|
||||
| `next-env.d.ts` | TypeScript declaration file for Next.js |
|
||||
| `tsconfig.json` | Configuration file for TypeScript |
|
||||
| `jsconfig.json` | Configuration file for JavaScript |
|
||||
| | |
|
||||
| -------------------------------------------------------------------------------------- | --------------------------------------- |
|
||||
| **Next.js** | |
|
||||
| [`next.config.js`](/docs/app/api-reference/config/next-config-js) | Configuration file for Next.js |
|
||||
| [`package.json`](/docs/app/getting-started/installation#manual-installation) | Project dependencies and scripts |
|
||||
| [`instrumentation.ts`](/docs/app/building-your-application/optimizing/instrumentation) | OpenTelemetry and Instrumentation file |
|
||||
| [`middleware.ts`](/docs/app/building-your-application/routing/middleware) | Next.js request middleware |
|
||||
| [`.env`](/docs/app/guides/environment-variables) | Environment variables |
|
||||
| [`.env.local`](/docs/app/guides/environment-variables) | Local environment variables |
|
||||
| [`.env.production`](/docs/app/guides/environment-variables) | Production environment variables |
|
||||
| [`.env.development`](/docs/app/guides/environment-variables) | Development environment variables |
|
||||
| [`.eslintrc.json`](/docs/app/api-reference/config/eslint) | Configuration file for ESLint |
|
||||
| `.gitignore` | Git files and folders to ignore |
|
||||
| `next-env.d.ts` | TypeScript declaration file for Next.js |
|
||||
| `tsconfig.json` | Configuration file for TypeScript |
|
||||
| `jsconfig.json` | Configuration file for JavaScript |
|
||||
|
||||
<AppOnly>
|
||||
|
||||
|
||||
@@ -531,7 +531,7 @@ There are two types of sessions:
|
||||
|
||||
To create and manage stateless sessions, there are a few steps you need to follow:
|
||||
|
||||
1. Generate a secret key, which will be used to sign your session, and store it as an [environment variable](/docs/app/building-your-application/configuring/environment-variables).
|
||||
1. Generate a secret key, which will be used to sign your session, and store it as an [environment variable](/docs/app/guides/environment-variables).
|
||||
2. Write logic to encrypt/decrypt session data using a session management library.
|
||||
3. Manage cookies using the Next.js [`cookies`](/docs/app/api-reference/functions/cookies) API.
|
||||
|
||||
@@ -547,7 +547,7 @@ There are a few ways you can generate secret key to sign your session. For examp
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
This command generates a 32-character random string that you can use as your secret key and store in your [environment variables file](/docs/app/building-your-application/configuring/environment-variables):
|
||||
This command generates a 32-character random string that you can use as your secret key and store in your [environment variables file](/docs/app/guides/environment-variables):
|
||||
|
||||
```bash filename=".env"
|
||||
SESSION_SECRET=your_secret_key
|
||||
|
||||
+2
-1
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Content Security Policy
|
||||
title: How to set a Content Security Policy (CSP) for your Next.js application
|
||||
nav_title: Content Security Policy
|
||||
description: Learn how to set a Content Security Policy (CSP) for your Next.js application.
|
||||
related:
|
||||
links:
|
||||
+2
-1
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Custom Server
|
||||
title: How to set up a custom server in Next.js
|
||||
nav_title: Custom Server
|
||||
description: Start a Next.js app programmatically using a custom server.
|
||||
---
|
||||
|
||||
+2
-1
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Debugging
|
||||
title: How to use debugging tools with Next.js
|
||||
nav_title: Debugging
|
||||
description: Learn how to debug your Next.js application with VS Code, Chrome DevTools, or Firefox DevTools.
|
||||
---
|
||||
|
||||
+2
-1
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Draft Mode
|
||||
title: How to preview content with Draft Mode in Next.js
|
||||
nav_title: Draft Mode
|
||||
description: Next.js has draft mode to toggle between static and dynamic pages. You can learn how it works with App Router here.
|
||||
related:
|
||||
title: Next Steps
|
||||
+2
-1
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Environment Variables
|
||||
title: How to use environment variables in Next.js
|
||||
nav_title: Environment Variables
|
||||
description: Learn to add and access environment variables in your Next.js application.
|
||||
---
|
||||
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Markdown and MDX
|
||||
title: How to use markdown and MDX in Next.js
|
||||
nav_title: MDX
|
||||
description: Learn how to configure MDX and use it in your Next.js apps.
|
||||
---
|
||||
@@ -444,7 +444,7 @@ Alternatively, you can reference the public URL for the image asset based on the
|
||||
|
||||
### Step 9: Migrate Environment Variables
|
||||
|
||||
Next.js supports [environment variables](/docs/app/building-your-application/configuring/environment-variables) similarly to CRA but **requires** a `NEXT_PUBLIC_` prefix for any variable you want to expose in the browser.
|
||||
Next.js supports [environment variables](/docs/app/guides/environment-variables) similarly to CRA but **requires** a `NEXT_PUBLIC_` prefix for any variable you want to expose in the browser.
|
||||
|
||||
The main difference is the prefix used to expose environment variables on the client-side. Change all environment variables with the `REACT_APP_` prefix to `NEXT_PUBLIC_`.
|
||||
|
||||
@@ -505,7 +505,7 @@ export default nextConfig
|
||||
|
||||
### Handling a Custom `Service Worker`
|
||||
|
||||
If you used CRA’s service worker (e.g., `serviceWorker.js` from `create-react-app`), you can learn how to create [Progressive Web Applications (PWAs)](/docs/app/building-your-application/configuring/progressive-web-apps) with Next.js.
|
||||
If you used CRA’s service worker (e.g., `serviceWorker.js` from `create-react-app`), you can learn how to create [Progressive Web Applications (PWAs)](/docs/app/guides/progressive-web-apps) with Next.js.
|
||||
|
||||
### Proxying API Requests
|
||||
|
||||
|
||||
@@ -507,7 +507,7 @@ Alternatively, you can reference the public URL for the image asset based on the
|
||||
### Step 7: Migrate the Environment Variables
|
||||
|
||||
Next.js has support for `.env`
|
||||
[environment variables](/docs/app/building-your-application/configuring/environment-variables)
|
||||
[environment variables](/docs/app/guides/environment-variables)
|
||||
similar to Vite. The main difference is the prefix used to expose environment variables on the
|
||||
client-side.
|
||||
|
||||
|
||||
@@ -101,8 +101,8 @@ While building your application, we recommend using the following features to en
|
||||
|
||||
</AppOnly>
|
||||
|
||||
- **[Environment Variables](/docs/app/building-your-application/configuring/environment-variables):** Ensure your `.env.*` files are added to `.gitignore` and only public variables are prefixed with `NEXT_PUBLIC_`.
|
||||
- **[Content Security Policy](/docs/app/building-your-application/configuring/content-security-policy):** Consider adding a Content Security Policy to protect your application against various security threats such as cross-site scripting, clickjacking, and other code injection attacks.
|
||||
- **[Environment Variables](/docs/app/guides/environment-variables):** Ensure your `.env.*` files are added to `.gitignore` and only public variables are prefixed with `NEXT_PUBLIC_`.
|
||||
- **[Content Security Policy](/docs/app/guides/content-security-policy):** Consider adding a Content Security Policy to protect your application against various security threats such as cross-site scripting, clickjacking, and other code injection attacks.
|
||||
|
||||
### Metadata and SEO
|
||||
|
||||
|
||||
+3
-2
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Progressive Web Applications (PWA)
|
||||
title: How to build a Progressive Web Application (PWA) with Next.js
|
||||
nav_title: PWAs
|
||||
description: Learn how to build a Progressive Web Application (PWA) with Next.js.
|
||||
related:
|
||||
links:
|
||||
@@ -645,7 +646,7 @@ Let’s go over each of these options:
|
||||
2. `Cache-Control: no-cache, no-store, must-revalidate`: Prevents caching of the service worker, ensuring users always get the latest version.
|
||||
3. `Content-Security-Policy: default-src 'self'; script-src 'self'`: Implements a strict Content Security Policy for the service worker, only allowing scripts from the same origin.
|
||||
|
||||
Learn more about defining [Content Security Policies](/docs/app/building-your-application/configuring/content-security-policy) with Next.js.
|
||||
Learn more about defining [Content Security Policies](/docs/app/guides/content-security-policy) with Next.js.
|
||||
|
||||
## Next Steps
|
||||
|
||||
@@ -77,7 +77,7 @@ Image Optimization can be used with a [static export](/docs/app/guides/static-ex
|
||||
|
||||
Middleware uses a [runtime](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) that is a subset of all available Node.js APIs to help ensure low latency, since it may run in front of every route or asset in your application. This runtime does not require running “at the edge” and works in a single-region server. Additional configuration and infrastructure are required to run Middleware in multiple regions.
|
||||
|
||||
If you are looking to add logic (or use an external package) that requires all Node.js APIs, you might be able to move this logic to a [layout](/docs/app/building-your-application/routing/layouts-and-templates#layouts) as a [Server Component](/docs/app/building-your-application/rendering/server-components). For example, checking [headers](/docs/app/api-reference/functions/headers) and [redirecting](/docs/app/api-reference/functions/redirect). You can also use headers, cookies, or query parameters to [redirect](/docs/app/api-reference/config/next-config-js/redirects#header-cookie-and-query-matching) or [rewrite](/docs/app/api-reference/config/next-config-js/rewrites#header-cookie-and-query-matching) through `next.config.js`. If that does not work, you can also use a [custom server](/docs/pages/building-your-application/configuring/custom-server).
|
||||
If you are looking to add logic (or use an external package) that requires all Node.js APIs, you might be able to move this logic to a [layout](/docs/app/building-your-application/routing/layouts-and-templates#layouts) as a [Server Component](/docs/app/building-your-application/rendering/server-components). For example, checking [headers](/docs/app/api-reference/functions/headers) and [redirecting](/docs/app/api-reference/functions/redirect). You can also use headers, cookies, or query parameters to [redirect](/docs/app/api-reference/config/next-config-js/redirects#header-cookie-and-query-matching) or [rewrite](/docs/app/api-reference/config/next-config-js/rewrites#header-cookie-and-query-matching) through `next.config.js`. If that does not work, you can also use a [custom server](/docs/pages/guides/custom-server).
|
||||
|
||||
### Environment Variables
|
||||
|
||||
@@ -142,7 +142,7 @@ You can configure the Next.js cache location if you want to persist cached pages
|
||||
|
||||
- Next.js sets the `Cache-Control` header of `public, max-age=31536000, immutable` to truly immutable assets. It cannot be overridden. These immutable files contain a SHA-hash in the file name, so they can be safely cached indefinitely. For example, [Static Image Imports](/docs/app/building-your-application/optimizing/images#local-images). You can [configure the TTL](/docs/app/api-reference/components/image#caching-behavior) for images.
|
||||
- Incremental Static Regeneration (ISR) sets the `Cache-Control` header of `s-maxage: <revalidate in getStaticProps>, stale-while-revalidate`. This revalidation time is defined in your [`getStaticProps` function](/docs/pages/building-your-application/data-fetching/get-static-props) in seconds. If you set `revalidate: false`, it will default to a one-year cache duration.
|
||||
- Dynamically rendered pages set a `Cache-Control` header of `private, no-cache, no-store, max-age=0, must-revalidate` to prevent user-specific data from being cached. This applies to both the App Router and Pages Router. This also includes [Draft Mode](/docs/app/building-your-application/configuring/draft-mode).
|
||||
- Dynamically rendered pages set a `Cache-Control` header of `private, no-cache, no-store, max-age=0, must-revalidate` to prevent user-specific data from being cached. This applies to both the App Router and Pages Router. This also includes [Draft Mode](/docs/app/guides/draft-mode).
|
||||
|
||||
#### Static Assets
|
||||
|
||||
|
||||
@@ -287,7 +287,7 @@ Features that require a Node.js server, or dynamic logic that cannot be computed
|
||||
- [Middleware](/docs/app/building-your-application/routing/middleware)
|
||||
- [Incremental Static Regeneration](/docs/app/building-your-application/data-fetching/incremental-static-regeneration)
|
||||
- [Image Optimization](/docs/app/building-your-application/optimizing/images) with the default `loader`
|
||||
- [Draft Mode](/docs/app/building-your-application/configuring/draft-mode)
|
||||
- [Draft Mode](/docs/app/guides/draft-mode)
|
||||
- [Server Actions](/docs/app/building-your-application/data-fetching/server-actions-and-mutations)
|
||||
- [Intercepting Routes](/docs/app/building-your-application/routing/intercepting-routes)
|
||||
|
||||
@@ -309,7 +309,7 @@ export const dynamic = 'error'
|
||||
- [Middleware](/docs/pages/building-your-application/routing/middleware)
|
||||
- [Incremental Static Regeneration](/docs/pages/building-your-application/data-fetching/incremental-static-regeneration)
|
||||
- [Image Optimization](/docs/pages/building-your-application/optimizing/images) with the default `loader`
|
||||
- [Draft Mode](/docs/pages/building-your-application/configuring/draft-mode)
|
||||
- [Draft Mode](/docs/pages/guides/draft-mode)
|
||||
- [`getStaticPaths` with `fallback: true`](/docs/pages/api-reference/functions/get-static-paths#fallback-true)
|
||||
- [`getStaticPaths` with `fallback: 'blocking'`](/docs/pages/api-reference/functions/get-static-paths#fallback-blocking)
|
||||
- [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props)
|
||||
|
||||
@@ -97,7 +97,7 @@ Under the hood, `next/jest` is automatically configuring Jest for you, including
|
||||
- Ignoring `.next` from test resolving.
|
||||
- Loading `next.config.js` for flags that enable SWC transforms.
|
||||
|
||||
> **Good to know**: To test environment variables directly, load them manually in a separate setup script or in your `jest.config.ts` file. For more information, please see [Test Environment Variables](/docs/app/building-your-application/configuring/environment-variables#test-environment-variables).
|
||||
> **Good to know**: To test environment variables directly, load them manually in a separate setup script or in your `jest.config.ts` file. For more information, please see [Test Environment Variables](/docs/app/guides/environment-variables#test-environment-variables).
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
|
||||
@@ -352,7 +352,7 @@ Options to pass to the `<GoogleAnalytics>` component.
|
||||
| --------------- | -------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `gaId` | Required | Your [measurement ID](https://support.google.com/analytics/answer/12270356). Usually starts with `G-`. |
|
||||
| `dataLayerName` | Optional | Name of the data layer. Defaults to `dataLayer`. |
|
||||
| `nonce` | Optional | A [nonce](/docs/app/building-your-application/configuring/content-security-policy#nonces). |
|
||||
| `nonce` | Optional | A [nonce](/docs/app/guides/content-security-policy#nonces). |
|
||||
|
||||
### Google Maps Embed
|
||||
|
||||
|
||||
@@ -4,10 +4,10 @@ description: API reference for the mdx-components.js file.
|
||||
related:
|
||||
title: Learn more about MDX Components
|
||||
links:
|
||||
- app/building-your-application/configuring/mdx
|
||||
- app/guides/mdx
|
||||
---
|
||||
|
||||
The `mdx-components.js|tsx` file is **required** to use [`@next/mdx` with App Router](/docs/app/building-your-application/configuring/mdx) and will not work without it. Additionally, you can use it to [customize styles](/docs/app/building-your-application/configuring/mdx#using-custom-styles-and-components).
|
||||
The `mdx-components.js|tsx` file is **required** to use [`@next/mdx` with App Router](/docs/app/guides/mdx) and will not work without it. Additionally, you can use it to [customize styles](/docs/app/guides/mdx#using-custom-styles-and-components).
|
||||
|
||||
Use the file `mdx-components.tsx` (or `.js`) in the root of your project to define MDX Components. For example, at the same level as `pages` or `app`, or inside `src` if applicable.
|
||||
|
||||
|
||||
@@ -5,10 +5,10 @@ related:
|
||||
title: Next Steps
|
||||
description: Learn how to use Draft Mode with this step-by-step guide.
|
||||
links:
|
||||
- app/building-your-application/configuring/draft-mode
|
||||
- app/guides/draft-mode
|
||||
---
|
||||
|
||||
`draftMode` is an **async** function allows you to enable and disable [Draft Mode](/docs/app/building-your-application/configuring/draft-mode), as well as check if Draft Mode is enabled in a [Server Component](/docs/app/building-your-application/rendering/server-components).
|
||||
`draftMode` is an **async** function allows you to enable and disable [Draft Mode](/docs/app/guides/draft-mode), as well as check if Draft Mode is enabled in a [Server Component](/docs/app/building-your-application/rendering/server-components).
|
||||
|
||||
```tsx filename="app/page.ts" switcher
|
||||
import { draftMode } from 'next/headers'
|
||||
|
||||
@@ -7,25 +7,25 @@ description: Learn to add and access environment variables in your Next.js appli
|
||||
|
||||
<AppOnly>
|
||||
|
||||
> Since the release of [Next.js 9.4](https://nextjs.org/blog/next-9-4) we now have a more intuitive and ergonomic experience for [adding environment variables](/docs/app/building-your-application/configuring/environment-variables). Give it a try!
|
||||
> Since the release of [Next.js 9.4](https://nextjs.org/blog/next-9-4) we now have a more intuitive and ergonomic experience for [adding environment variables](/docs/app/guides/environment-variables). Give it a try!
|
||||
|
||||
</AppOnly>
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
> Since the release of [Next.js 9.4](https://nextjs.org/blog/next-9-4) we now have a more intuitive and ergonomic experience for [adding environment variables](/docs/pages/building-your-application/configuring/environment-variables). Give it a try!
|
||||
> Since the release of [Next.js 9.4](https://nextjs.org/blog/next-9-4) we now have a more intuitive and ergonomic experience for [adding environment variables](/docs/pages/guides/environment-variables). Give it a try!
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
<AppOnly>
|
||||
|
||||
> **Good to know**: environment variables specified in this way will **always** be included in the JavaScript bundle, prefixing the environment variable name with `NEXT_PUBLIC_` only has an effect when specifying them [through the environment or .env files](/docs/app/building-your-application/configuring/environment-variables).
|
||||
> **Good to know**: environment variables specified in this way will **always** be included in the JavaScript bundle, prefixing the environment variable name with `NEXT_PUBLIC_` only has an effect when specifying them [through the environment or .env files](/docs/app/guides/environment-variables).
|
||||
|
||||
</AppOnly>
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
> **Good to know**: environment variables specified in this way will **always** be included in the JavaScript bundle, prefixing the environment variable name with `NEXT_PUBLIC_` only has an effect when specifying them [through the environment or .env files](/docs/pages/building-your-application/configuring/environment-variables).
|
||||
> **Good to know**: environment variables specified in this way will **always** be included in the JavaScript bundle, prefixing the environment variable name with `NEXT_PUBLIC_` only has an effect when specifying them [through the environment or .env files](/docs/pages/guides/environment-variables).
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
|
||||
@@ -531,7 +531,7 @@ If you're deploying to [Vercel](https://vercel.com/docs/concepts/edge-network/he
|
||||
|
||||
[This header](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Frame-Options) indicates whether the site should be allowed to be displayed within an `iframe`. This can prevent against clickjacking attacks.
|
||||
|
||||
**This header has been superseded by CSP's `frame-ancestors` option**, which has better support in modern browsers (see [Content Security Policy](/docs/app/building-your-application/configuring/content-security-policy) for configuration details).
|
||||
**This header has been superseded by CSP's `frame-ancestors` option**, which has better support in modern browsers (see [Content Security Policy](/docs/app/guides/content-security-policy) for configuration details).
|
||||
|
||||
```js
|
||||
{
|
||||
@@ -577,7 +577,7 @@ For example, a user trying to download an image, but having it treated as a diff
|
||||
|
||||
### Content-Security-Policy
|
||||
|
||||
Learn more about adding a [Content Security Policy](/docs/app/building-your-application/configuring/content-security-policy) to your application.
|
||||
Learn more about adding a [Content Security Policy](/docs/app/guides/content-security-policy) to your application.
|
||||
|
||||
## Version History
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ Before continuing to add custom webpack configuration to your application make s
|
||||
- [CSS modules](/docs/pages/building-your-application/styling/css)
|
||||
- [Sass/SCSS imports](/docs/pages/building-your-application/styling/sass)
|
||||
- [Sass/SCSS modules](/docs/pages/building-your-application/styling/sass)
|
||||
- [Customizing babel configuration](/docs/pages/building-your-application/configuring/babel)
|
||||
- [Customizing babel configuration](/docs/pages/guides/babel)
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
|
||||
@@ -273,7 +273,7 @@ If the following conditions are true:
|
||||
- `react-hooks`
|
||||
- `jsx-a11y`
|
||||
- `import`
|
||||
- You've defined specific `parserOptions` that are different from how Babel is configured within Next.js (this is not recommended unless you have [customized your Babel configuration](/docs/pages/building-your-application/configuring/babel))
|
||||
- You've defined specific `parserOptions` that are different from how Babel is configured within Next.js (this is not recommended unless you have [customized your Babel configuration](/docs/pages/guides/babel))
|
||||
- You have `eslint-plugin-import` installed with Node.js and/or TypeScript [resolvers](https://github.com/benmosher/eslint-plugin-import#resolvers) defined to handle imports
|
||||
|
||||
Then we recommend either removing these settings if you prefer how these properties have been configured within [`eslint-config-next`](https://github.com/vercel/next.js/blob/canary/packages/eslint-config-next/index.js) or extending directly from the Next.js ESLint plugin instead:
|
||||
|
||||
@@ -126,7 +126,7 @@ The Next.js Edge Runtime is used for Middleware and supports the following APIs:
|
||||
|
||||
## Environment Variables
|
||||
|
||||
You can use `process.env` to access [Environment Variables](/docs/app/building-your-application/configuring/environment-variables) for both `next dev` and `next build`.
|
||||
You can use `process.env` to access [Environment Variables](/docs/app/guides/environment-variables) for both `next dev` and `next build`.
|
||||
|
||||
## Unsupported APIs
|
||||
|
||||
|
||||
+3
-2
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: AMP
|
||||
title: How to create AMP pages in Next.js
|
||||
nav_title: AMP
|
||||
description: With minimal config, and without leaving React, you can start adding AMP and improve the performance and speed of your pages.
|
||||
---
|
||||
|
||||
@@ -16,7 +17,7 @@ You can read more about AMP in the official [amp.dev](https://amp.dev/) site.
|
||||
|
||||
## Enabling AMP
|
||||
|
||||
To enable AMP support for a page, and to learn more about the different AMP configs, read the [API documentation for `next/amp`](/docs/pages/building-your-application/configuring/amp).
|
||||
To enable AMP support for a page, and to learn more about the different AMP configs, read the [API documentation for `next/amp`](/docs/pages/guides/amp).
|
||||
|
||||
## Caveats
|
||||
|
||||
+2
-1
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Babel
|
||||
title: How to configure Babel in Next.js
|
||||
nav_title: Babel
|
||||
description: Extend the babel preset added by Next.js with your own configs.
|
||||
---
|
||||
|
||||
+3
-2
@@ -1,7 +1,8 @@
|
||||
---
|
||||
title: Content Security Policy
|
||||
title: How to set a Content Security Policy (CSP) for your Next.js application
|
||||
nav_title: Content Security Policy
|
||||
description: Learn how to set a Content Security Policy (CSP) for your Next.js application.
|
||||
source: app/building-your-application/configuring/content-security-policy
|
||||
source: app/guides/content-security-policy
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. 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. */}
|
||||
+3
-2
@@ -1,7 +1,8 @@
|
||||
---
|
||||
title: Custom Server
|
||||
title: How to set up a custom server in Next.js
|
||||
nav_title: Custom Server
|
||||
description: Start a Next.js app programmatically using a custom server.
|
||||
source: app/building-your-application/configuring/custom-server
|
||||
source: app/guides/custom-server
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. 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. */}
|
||||
+3
-2
@@ -1,7 +1,8 @@
|
||||
---
|
||||
title: Debugging
|
||||
title: How to use debugging tools with Next.js
|
||||
nav_title: Debugging
|
||||
description: Learn how to debug your Next.js application with VS Code or Chrome DevTools.
|
||||
source: app/building-your-application/configuring/debugging
|
||||
source: app/guides/debugging
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. 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. */}
|
||||
+2
-1
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Draft Mode
|
||||
title: How to preview content with Draft Mode in Next.js
|
||||
nav_title: Draft Mode
|
||||
description: Next.js has draft mode to toggle between static and dynamic pages. You can learn how it works with Pages Router.
|
||||
---
|
||||
|
||||
+3
-2
@@ -1,7 +1,8 @@
|
||||
---
|
||||
title: Environment Variables
|
||||
title: How to use environment variables in Next.js
|
||||
nav_title: Environment Variables
|
||||
description: Learn to add and access environment variables in your Next.js application.
|
||||
source: app/building-your-application/configuring/environment-variables
|
||||
source: app/guides/environment-variables
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. 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. */}
|
||||
+2
-2
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Markdown and MDX
|
||||
title: How to use markdown and MDX in Next.js
|
||||
nav_title: MDX
|
||||
description: Learn how to configure MDX to write JSX in your markdown files.
|
||||
source: app/building-your-application/configuring/mdx
|
||||
source: app/guides/mdx
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. 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. */}
|
||||
+2
-1
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: PostCSS
|
||||
title: How to configure PostCSS in Next.js
|
||||
nav_title: PostCSS
|
||||
description: Extend the PostCSS config and plugins added by Next.js with your own.
|
||||
---
|
||||
|
||||
+3
-2
@@ -1,9 +1,10 @@
|
||||
---
|
||||
title: Preview Mode
|
||||
title: How to preview content with Preview Mode in Next.js
|
||||
nav_title: Preview Mode
|
||||
description: Next.js has the preview mode for statically generated pages. You can learn how it works here.
|
||||
---
|
||||
|
||||
> **Note**: This feature is superseded by [Draft Mode](/docs/pages/building-your-application/configuring/draft-mode).
|
||||
> **Note**: This feature is superseded by [Draft Mode](/docs/pages/guides/draft-mode).
|
||||
|
||||
<details>
|
||||
<summary>Examples</summary>
|
||||
@@ -48,7 +48,7 @@ bun add react@latest react-dom@latest
|
||||
|
||||
Next.js now uses the Rust-based compiler [SWC](https://swc.rs/) to compile JavaScript/TypeScript. This new compiler is up to 17x faster than Babel when compiling individual files and up to 5x faster Fast Refresh.
|
||||
|
||||
Next.js provides full backward compatibility with applications that have [custom Babel configuration](/docs/pages/building-your-application/configuring/babel). All transformations that Next.js handles by default like styled-jsx and tree-shaking of `getStaticProps` / `getStaticPaths` / `getServerSideProps` have been ported to Rust.
|
||||
Next.js provides full backward compatibility with applications that have [custom Babel configuration](/docs/pages/guides/babel). All transformations that Next.js handles by default like styled-jsx and tree-shaking of `getStaticProps` / `getStaticPaths` / `getServerSideProps` have been ported to Rust.
|
||||
|
||||
When an application has a custom Babel configuration, Next.js will automatically opt-out of using SWC for compiling JavaScript/Typescript and will fall back to using Babel in the same way that it was used in Next.js 11.
|
||||
|
||||
|
||||
@@ -95,4 +95,4 @@ If you have a custom `Error` component be sure to import that one instead. `next
|
||||
### Caveats
|
||||
|
||||
- `Error` does not currently support Next.js [Data Fetching methods](/docs/pages/building-your-application/data-fetching) like [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) or [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props).
|
||||
- `_error`, like `_app`, is a reserved pathname. `_error` is used to define the customized layouts and behaviors of the error pages. `/_error` will render 404 when accessed directly via [routing](/docs/pages/building-your-application/routing) or rendering in a [custom server](/docs/pages/building-your-application/configuring/custom-server).
|
||||
- `_error`, like `_app`, is a reserved pathname. `_error` is used to define the customized layouts and behaviors of the error pages. `/_error` will render 404 when accessed directly via [routing](/docs/pages/building-your-application/routing) or rendering in a [custom server](/docs/pages/guides/custom-server).
|
||||
|
||||
@@ -199,4 +199,4 @@ In development (`next dev`), `getStaticProps` will be called on every request.
|
||||
|
||||
## Preview Mode
|
||||
|
||||
You can temporarily bypass static generation and render the page at **request time** instead of build time using [**Preview Mode**](/docs/pages/building-your-application/configuring/preview-mode). For example, you might be using a headless CMS and want to preview drafts before they're published.
|
||||
You can temporarily bypass static generation and render the page at **request time** instead of build time using [**Preview Mode**](/docs/pages/guides/preview-mode). For example, you might be using a headless CMS and want to preview drafts before they're published.
|
||||
|
||||
+1
-1
@@ -10,7 +10,7 @@ Forms enable you to create and update data in web applications. Next.js provides
|
||||
>
|
||||
> - We will soon recommend [incrementally adopting](/docs/app/guides/migrating/app-router-migration) the App Router and using [Server Actions](/docs/app/building-your-application/data-fetching/server-actions-and-mutations) for handling form submissions and data mutations. Server Actions allow you to define asynchronous server functions that can be called directly from your components, without needing to manually create an API Route.
|
||||
> - API Routes [do not specify CORS headers](https://developer.mozilla.org/docs/Web/HTTP/CORS), meaning they are same-origin only by default.
|
||||
> - Since API Routes run on the server, we're able to use sensitive values (like API keys) through [Environment Variables](/docs/pages/building-your-application/configuring/environment-variables) without exposing them to the client. This is critical for the security of your application.
|
||||
> - Since API Routes run on the server, we're able to use sensitive values (like API keys) through [Environment Variables](/docs/pages/guides/environment-variables) without exposing them to the client. This is critical for the security of your application.
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -62,9 +62,9 @@ The `context` parameter is an object containing the following keys:
|
||||
| `req` | [The `HTTP` IncomingMessage object](https://nodejs.org/api/http.html#http_class_http_incomingmessage), with an additional `cookies` prop, which is an object with string keys mapping to string values of cookies. |
|
||||
| `res` | [The `HTTP` response object](https://nodejs.org/api/http.html#http_class_http_serverresponse). |
|
||||
| `query` | An object representing the query string, including dynamic route parameters. |
|
||||
| `preview` | (Deprecated for `draftMode`) `preview` is `true` if the page is in the [Preview Mode](/docs/pages/building-your-application/configuring/preview-mode) and `false` otherwise. |
|
||||
| `previewData` | (Deprecated for `draftMode`) The [preview](/docs/pages/building-your-application/configuring/preview-mode) data set by `setPreviewData`. |
|
||||
| `draftMode` | `draftMode` is `true` if the page is in the [Draft Mode](/docs/pages/building-your-application/configuring/draft-mode) and `false` otherwise. |
|
||||
| `preview` | (Deprecated for `draftMode`) `preview` is `true` if the page is in the [Preview Mode](/docs/pages/guides/preview-mode) and `false` otherwise. |
|
||||
| `previewData` | (Deprecated for `draftMode`) The [preview](/docs/pages/guides/preview-mode) data set by `setPreviewData`. |
|
||||
| `draftMode` | `draftMode` is `true` if the page is in the [Draft Mode](/docs/pages/guides/draft-mode) and `false` otherwise. |
|
||||
| `resolvedUrl` | A normalized version of the request `URL` that strips the `_next/data` prefix for client transitions and includes original query values. |
|
||||
| `locale` | Contains the active locale (if enabled). |
|
||||
| `locales` | Contains all supported locales (if enabled). |
|
||||
|
||||
@@ -49,9 +49,9 @@ The `context` parameter is an object containing the following keys:
|
||||
| Name | Description |
|
||||
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `params` | Contains the route parameters for pages using [dynamic routes](/docs/pages/building-your-application/routing/dynamic-routes). For example, if the page name is `[id].js`, then `params` will look like `{ id: ... }`. You should use this together with `getStaticPaths`, which we'll explain later. |
|
||||
| `preview` | (Deprecated for `draftMode`) `preview` is `true` if the page is in the [Preview Mode](/docs/pages/building-your-application/configuring/preview-mode) and `false` otherwise. |
|
||||
| `previewData` | (Deprecated for `draftMode`) The [preview](/docs/pages/building-your-application/configuring/preview-mode) data set by `setPreviewData`. |
|
||||
| `draftMode` | `draftMode` is `true` if the page is in the [Draft Mode](/docs/pages/building-your-application/configuring/draft-mode) and `false` otherwise. |
|
||||
| `preview` | (Deprecated for `draftMode`) `preview` is `true` if the page is in the [Preview Mode](/docs/pages/guides/preview-mode) and `false` otherwise. |
|
||||
| `previewData` | (Deprecated for `draftMode`) The [preview](/docs/pages/guides/preview-mode) data set by `setPreviewData`. |
|
||||
| `draftMode` | `draftMode` is `true` if the page is in the [Draft Mode](/docs/pages/guides/draft-mode) and `false` otherwise. |
|
||||
| `locale` | Contains the active locale (if enabled). |
|
||||
| `locales` | Contains all supported locales (if enabled). |
|
||||
| `defaultLocale` | Contains the configured default locale (if enabled). |
|
||||
|
||||
@@ -10,7 +10,7 @@ description: Enable AMP in a page, and control the way Next.js adds AMP to the p
|
||||
|
||||
</details>
|
||||
|
||||
> AMP support is one of our advanced features, you can [read more about AMP here](/docs/pages/building-your-application/configuring/amp).
|
||||
> AMP support is one of our advanced features, you can [read more about AMP here](/docs/pages/guides/amp).
|
||||
|
||||
To enable AMP, add the following config to your page:
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ The following is the definition of the `router` object returned by both [`useRou
|
||||
- `defaultLocale`: `String` - The current default locale (if enabled).
|
||||
- `domainLocales`: `Array<{domain, defaultLocale, locales}>` - Any configured domain locales.
|
||||
- `isReady`: `boolean` - Whether the router fields are updated client-side and ready for use. Should only be used inside of `useEffect` methods and not for conditionally rendering on the server. See related docs for use case with [automatically statically optimized pages](/docs/pages/building-your-application/rendering/automatic-static-optimization)
|
||||
- `isPreview`: `boolean` - Whether the application is currently in [preview mode](/docs/pages/building-your-application/configuring/preview-mode).
|
||||
- `isPreview`: `boolean` - Whether the application is currently in [preview mode](/docs/pages/guides/preview-mode).
|
||||
|
||||
> Using the `asPath` field may lead to a mismatch between client and server if the page is rendered using server-side rendering or [automatic static optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization). Avoid using `asPath` until the `isReady` field is `true`.
|
||||
|
||||
@@ -276,7 +276,7 @@ export default function Login() {
|
||||
|
||||
### router.beforePopState
|
||||
|
||||
In some cases (for example, if using a [Custom Server](/docs/pages/building-your-application/configuring/custom-server)), you may wish to listen to [popstate](https://developer.mozilla.org/docs/Web/API/Window/popstate_event) and do something before the router acts on it.
|
||||
In some cases (for example, if using a [Custom Server](/docs/pages/guides/custom-server)), you may wish to listen to [popstate](https://developer.mozilla.org/docs/Web/API/Window/popstate_event) and do something before the router acts on it.
|
||||
|
||||
```js
|
||||
router.beforePopState(cb)
|
||||
@@ -287,7 +287,7 @@ router.beforePopState(cb)
|
||||
- `as`: `String` - the url that will be shown in the browser
|
||||
- `options`: `Object` - Additional options sent by [router.push](#routerpush)
|
||||
|
||||
If `cb` returns `false`, the Next.js router will not handle `popstate`, and you'll be responsible for handling it in that case. See [Disabling file-system routing](/docs/pages/building-your-application/configuring/custom-server#disabling-file-system-routing).
|
||||
If `cb` returns `false`, the Next.js router will not handle `popstate`, and you'll be responsible for handling it in that case. See [Disabling file-system routing](/docs/pages/guides/custom-server#disabling-file-system-routing).
|
||||
|
||||
You could use `beforePopState` to manipulate the request, or force a SSR refresh, as in the following example:
|
||||
|
||||
|
||||
+1
-1
@@ -5,7 +5,7 @@ description: Add client and server runtime configuration to your Next.js app.
|
||||
|
||||
> **Warning:**
|
||||
>
|
||||
> - **This feature is deprecated.** We recommend using [environment variables](/docs/pages/building-your-application/configuring/environment-variables) instead, which also can support reading runtime values.
|
||||
> - **This feature is deprecated.** We recommend using [environment variables](/docs/pages/guides/environment-variables) instead, which also can support reading runtime values.
|
||||
> - You can run code on server startup using the [`register` function](/docs/app/building-your-application/optimizing/instrumentation).
|
||||
> - This feature does not work with [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization), [Output File Tracing](/docs/pages/api-reference/config/next-config-js/output#automatically-copying-traced-files), or [React Server Components](/docs/app/building-your-application/rendering/server-components).
|
||||
|
||||
|
||||
@@ -63,4 +63,4 @@ Next.js has built-in TypeScript support. [Learn more here](/docs/pages/api-refer
|
||||
|
||||
### Customizing Babel Config (Advanced)
|
||||
|
||||
You can customize babel configuration. [Learn more here](/docs/pages/building-your-application/configuring/babel).
|
||||
You can customize babel configuration. [Learn more here](/docs/pages/guides/babel).
|
||||
|
||||
@@ -14,4 +14,4 @@ To address this issue, you should remove your custom Babel configuration (e.g. `
|
||||
## Useful Links
|
||||
|
||||
- [Next.js Compiler](/docs/architecture/nextjs-compiler) - Learn more about the Next.js Compiler and how it benefits your application.
|
||||
- [Customizing Babel Config](/docs/pages/building-your-application/configuring/babel) - Understand more about how to customize your Babel configuration in a Next.js application, and the implications of doing so.
|
||||
- [Customizing Babel Config](/docs/pages/guides/babel) - Understand more about how to customize your Babel configuration in a Next.js application, and the implications of doing so.
|
||||
|
||||
@@ -5,7 +5,7 @@ description: This document explains the "Build Directory Not Writeable" error in
|
||||
|
||||
## Why This Error Occurred
|
||||
|
||||
The "Build Directory Not Writeable" error usually occurs when the file system does not permit writing to the designated directory. A common scenario for this error is when you initiate a [custom server](/docs/pages/building-your-application/configuring/custom-server) in development mode on a production server.
|
||||
The "Build Directory Not Writeable" error usually occurs when the file system does not permit writing to the designated directory. A common scenario for this error is when you initiate a [custom server](/docs/pages/guides/custom-server) in development mode on a production server.
|
||||
|
||||
These production servers often disallow writing to the filesystem after your application is built, causing this error.
|
||||
|
||||
@@ -32,4 +32,4 @@ const app = next({ dev })
|
||||
|
||||
## Useful Links
|
||||
|
||||
- [Custom Server documentation + examples](/docs/pages/building-your-application/configuring/custom-server) - Learn more about how to effectively set up and manage an ejected server in Next.js.
|
||||
- [Custom Server documentation + examples](/docs/pages/guides/custom-server) - Learn more about how to effectively set up and manage an ejected server in Next.js.
|
||||
|
||||
@@ -19,4 +19,4 @@ Remove `dotenv` from your `devDependencies` or `dependencies` and allow Next.js
|
||||
- [dotenv](https://npmjs.com/package/dotenv)
|
||||
- [dotenv-expand](https://npmjs.com/package/dotenv-expand)
|
||||
- [Environment Variables](https://en.wikipedia.org/wiki/Environment_variable)
|
||||
- [Next.js Environment Variables Docs](/docs/pages/building-your-application/configuring/environment-variables)
|
||||
- [Next.js Environment Variables Docs](/docs/pages/guides/environment-variables)
|
||||
|
||||
@@ -16,4 +16,4 @@ Also ensure any type imports are kept inside of TypeScript files e.g. ensure `im
|
||||
|
||||
## Useful Links
|
||||
|
||||
- [Custom Server Documentation](/docs/pages/building-your-application/configuring/custom-server)
|
||||
- [Custom Server Documentation](/docs/pages/guides/custom-server)
|
||||
|
||||
@@ -116,6 +116,6 @@ export const config = {}
|
||||
|
||||
## Useful Links
|
||||
|
||||
- [Enabling AMP Support](/docs/pages/building-your-application/configuring/amp)
|
||||
- [Enabling AMP Support](/docs/pages/guides/amp)
|
||||
- [API Routes Request Helpers](/docs/pages/building-your-application/routing/api-routes)
|
||||
- [Edge and Node.js Runtimes](/docs/pages/building-your-application/rendering/edge-and-nodejs-runtimes)
|
||||
|
||||
@@ -17,8 +17,8 @@ invalid characters (any one of `<>&` characters). For example:
|
||||
|
||||
We recommend using a randomly generated UUID for your nonce.
|
||||
|
||||
Learn more about how to use nonces with Next.js in our [Content Security Policy](/docs/app/building-your-application/configuring/content-security-policy) docs.
|
||||
Learn more about how to use nonces with Next.js in our [Content Security Policy](/docs/app/guides/content-security-policy) docs.
|
||||
|
||||
## Useful Links
|
||||
|
||||
- [Content Security Policy](/docs/app/building-your-application/configuring/content-security-policy)
|
||||
- [Content Security Policy](/docs/app/guides/content-security-policy)
|
||||
|
||||
@@ -18,5 +18,5 @@ Remove the plugin specified in the error message from your custom PostCSS config
|
||||
|
||||
### How do I configure CSS Modules?
|
||||
|
||||
CSS Modules are supported in [Next.js' built-in CSS support](/docs/pages/building-your-application/configuring/post-css).
|
||||
You can [read more about how to use CSS Modules here](/docs/pages/building-your-application/configuring/post-css).
|
||||
CSS Modules are supported in [Next.js' built-in CSS support](/docs/pages/guides/post-css).
|
||||
You can [read more about how to use CSS Modules here](/docs/pages/guides/post-css).
|
||||
|
||||
@@ -41,7 +41,7 @@ module.exports = {
|
||||
}
|
||||
```
|
||||
|
||||
You can [read more about configuring PostCSS in Next.js here](/docs/pages/building-your-application/configuring/post-css).
|
||||
You can [read more about configuring PostCSS in Next.js here](/docs/pages/guides/post-css).
|
||||
|
||||
### Common Errors
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ title: SWC disabled
|
||||
|
||||
Next.js now uses Rust-based compiler [SWC](https://swc.rs/) to compile JavaScript/TypeScript. This new compiler is up to 17x faster than Babel when compiling individual files and up to 5x faster Fast Refresh.
|
||||
|
||||
Next.js provides full backwards compatibility with applications that have [custom Babel configuration](/docs/pages/building-your-application/configuring/babel). All transformations that Next.js handles by default like styled-jsx and tree-shaking of `getStaticProps` / `getStaticPaths` / `getServerSideProps` have been ported to Rust.
|
||||
Next.js provides full backwards compatibility with applications that have [custom Babel configuration](/docs/pages/guides/babel). All transformations that Next.js handles by default like styled-jsx and tree-shaking of `getStaticProps` / `getStaticPaths` / `getServerSideProps` have been ported to Rust.
|
||||
|
||||
When an application has custom Babel configuration Next.js will automatically opt-out of using SWC for compiling JavaScript/Typescript and will fall back to using Babel in the same way that it was used in Next.js 11.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user