The value of customKey is: {process.env.customKey}
-}
-
-export default Index
-```
-
-#### 运行时配置
-
-> ⚠️ 请注意，使用此选项时不可用 `target: 'serverless'`
-
-> ⚠️ 通常，您希望使用构建时配置来提供配置。原因是运行时配置增加了一个小的rendering/initialization开销。
-
-`next/config`模块使你应用运行时可以读取些存储在`next.config.js`的配置项。`serverRuntimeConfig`属性只在服务器端可用，`publicRuntimeConfig`属性在服务端和客户端可用。
-
-```js
-// next.config.js
-module.exports = {
- serverRuntimeConfig: {
- // Will only be available on the server side
- mySecret: 'secret',
- secondSecret: process.env.SECOND_SECRET // Pass through env variables
- },
- publicRuntimeConfig: {
- // Will be available on both server and client
- staticFolder: '/static'
- }
-}
-```
-
-```js
-// pages/index.js
-import getConfig from 'next/config'
-// Only holds serverRuntimeConfig and publicRuntimeConfig from next.config.js nothing else.
-const { serverRuntimeConfig, publicRuntimeConfig } = getConfig()
-
-console.log(serverRuntimeConfig.mySecret) // Will only be available on the server side
-console.log(publicRuntimeConfig.staticFolder) // Will be available on both server and client
-
-function MyImage() {
- return (
-
diff --git a/bench/rendering/readme.md b/bench/rendering/readme.md
new file mode 100644
index 0000000000000..71c7070d8f691
--- /dev/null
+++ b/bench/rendering/readme.md
@@ -0,0 +1,29 @@
+# Next.js server-side benchmarks
+
+## Installation
+
+Follow the steps in [contributing.md](../contributing.md)
+
+Both benchmarks use `ab`. So make sure you have that installed.
+
+## Usage
+
+Before running the test:
+
+```
+npm run start
+```
+
+Then run one of these tests:
+
+- Stateless application which renders `
My component!
`. Runs 3000 http requests.
+
+```
+npm run bench:stateless
+```
+
+- Stateless application which renders `
This is row {i}
` 10.000 times. Runs 500 http requests.
+
+```
+npm run bench:stateless-big
+```
diff --git a/bench/vercel/.env.dev b/bench/vercel/.env.dev
new file mode 100644
index 0000000000000..aaa722fd03652
--- /dev/null
+++ b/bench/vercel/.env.dev
@@ -0,0 +1,8 @@
+# The Vercel team you want to deploy the project too
+VERCEL_TEST_TEAM=
+
+# The corresponding Vercel token
+VERCEL_TEST_TOKEN=
+
+# The Vercel project you want to deploy the test project too
+VERCEL_TEST_PROJECT_NAME=
diff --git a/bench/vercel/.gitignore b/bench/vercel/.gitignore
new file mode 100644
index 0000000000000..753f9c1a3b423
--- /dev/null
+++ b/bench/vercel/.gitignore
@@ -0,0 +1,5 @@
+.vercel
+.next
+*.tgz
+yarn.lock
+.env
\ No newline at end of file
diff --git a/bench/vercel/README.md b/bench/vercel/README.md
new file mode 100644
index 0000000000000..5d8bce4c7e53b
--- /dev/null
+++ b/bench/vercel/README.md
@@ -0,0 +1,22 @@
+# Benchmarking Next.js on production
+
+This script allows you to measure some performance metrics of your local build of Next.js on production by uploading your current build to Vercel with an example app and running some basic benchmarks on it.
+
+## Requirements
+
+- the Vercel CLI
+
+## Setup
+
+Rename the provided `./env.local` file to `./env` and fill in the required `VERCEL_TEST_TOKEN` and `VERCEL_TEST_TEAM` values. You can find and generate those from vercel.com.
+
+Run `pnpm install`, `pnpm bench` and profit.
+
+Note: if you made some changes to Next.js, make sure you compiled them by running at the root of the monorepo either `pnpm dev` or `pnpm build --force`.
+
+## How it works
+
+- with the Vercel CLI, we setup a project
+- we `npm pack` the local Next build and add it to the repo
+- we upload the repo to Vercel and let it build
+- once it builds, we get the deployment url and run some tests
diff --git a/bench/vercel/bench.js b/bench/vercel/bench.js
new file mode 100644
index 0000000000000..7aea7631acb16
--- /dev/null
+++ b/bench/vercel/bench.js
@@ -0,0 +1,70 @@
+import { Command } from 'commander'
+import console from 'console'
+
+import chalk from 'chalk'
+
+import PQueue from 'p-queue'
+import { generateProjects, cleanupProjectFolders } from './project-utils.js'
+import { printBenchmarkResults } from './chart.js'
+import { genRetryableRequest } from './gen-request.js'
+
+const program = new Command()
+
+const queue = new PQueue({ concurrency: 25 })
+const TTFB_OUTLIERS_THRESHOLD = 250
+
+program.option('-p, --path ')
+
+program.parse(process.argv)
+
+const options = program.opts()
+
+if (options.path) {
+ console.log('Running benchmark for path: ', options.path)
+}
+
+try {
+ const [originDeploymentURL, headDeploymentURL] = await generateProjects()
+
+ const originBenchmarkURL = `${originDeploymentURL}${options.path || ''}`
+ const headBenchmarkURL = `${headDeploymentURL}${options.path || ''}`
+
+ console.log(`Origin deployment URL: ${originBenchmarkURL}`)
+ console.log(`Head deployment URL: ${headBenchmarkURL}`)
+ console.log(`Running benchmark...`)
+
+ const benchResults = await runBenchmark(originBenchmarkURL)
+
+ const headBenchResults = await runBenchmark(headBenchmarkURL)
+
+ console.log(chalk.bold('Benchmark results for cold:'))
+ printBenchmarkResults(
+ {
+ origin: benchResults,
+ head: headBenchResults,
+ },
+ (r) => r.cold && r.firstByte <= TTFB_OUTLIERS_THRESHOLD && r.firstByte
+ )
+ console.log(chalk.bold('Benchmark results for hot:'))
+ printBenchmarkResults(
+ {
+ origin: benchResults,
+ head: headBenchResults,
+ },
+ (r) => !r.cold && r.firstByte <= TTFB_OUTLIERS_THRESHOLD && r.firstByte
+ )
+} catch (err) {
+ console.log(chalk.red('Benchmark failed: ', err))
+} finally {
+ await cleanupProjectFolders()
+}
+
+async function runBenchmark(url) {
+ return (
+ await Promise.all(
+ Array.from({ length: 500 }).map(() =>
+ queue.add(() => genRetryableRequest(url))
+ )
+ )
+ ).filter(Boolean)
+}
diff --git a/bench/vercel/benchmark-app/.gitignore b/bench/vercel/benchmark-app/.gitignore
new file mode 100644
index 0000000000000..9a0fb41c7f85d
--- /dev/null
+++ b/bench/vercel/benchmark-app/.gitignore
@@ -0,0 +1,2 @@
+.vercel
+webpack-stats-client.json
\ No newline at end of file
diff --git a/bench/vercel/benchmark-app/app/layout.js b/bench/vercel/benchmark-app/app/layout.js
new file mode 100644
index 0000000000000..3a313aa413fdb
--- /dev/null
+++ b/bench/vercel/benchmark-app/app/layout.js
@@ -0,0 +1,14 @@
+import * as React from 'react'
+
+export default function Root({ children }) {
+ return (
+
+
+ {children}
+
+ )
+}
+
+export const config = {
+ runtime: 'experimental-edge',
+}
diff --git a/bench/vercel/benchmark-app/app/rsc/page.js b/bench/vercel/benchmark-app/app/rsc/page.js
new file mode 100644
index 0000000000000..7598427263e55
--- /dev/null
+++ b/bench/vercel/benchmark-app/app/rsc/page.js
@@ -0,0 +1,14 @@
+import * as React from 'react'
+
+// if (!('hot' in Math)) Math.hot = false
+
+export default function page() {
+ // const previous = Math.hot
+ // Math.hot = true
+ // return
{previous ? 'HOT' : 'COLD'}
+ return
hello
+}
+
+export const config = {
+ runtime: 'experimental-edge',
+}
diff --git a/bench/vercel/benchmark-app/next.config.js b/bench/vercel/benchmark-app/next.config.js
new file mode 100644
index 0000000000000..7041c1b531d4f
--- /dev/null
+++ b/bench/vercel/benchmark-app/next.config.js
@@ -0,0 +1,34 @@
+const { StatsWriterPlugin } = require('webpack-stats-plugin')
+const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer')
+
+module.exports = {
+ experimental: {
+ appDir: true,
+ },
+ webpack: (config, options) => {
+ const { nextRuntime = 'client' } = options
+ if (process.env.ANALYZE) {
+ if (nextRuntime === 'edge')
+ config.plugins.push(
+ new BundleAnalyzerPlugin({
+ analyzerMode: 'static',
+ openAnalyzer: true,
+ reportFilename: options.isServer
+ ? '../analyze/server.html'
+ : './analyze/client.html',
+ })
+ )
+ config.plugins.push(
+ new StatsWriterPlugin({
+ filename: `../webpack-stats-${nextRuntime}.json`,
+ stats: {
+ assets: true,
+ chunks: true,
+ modules: true,
+ },
+ })
+ )
+ }
+ return config
+ },
+}
diff --git a/bench/vercel/benchmark-app/package.json b/bench/vercel/benchmark-app/package.json
new file mode 100644
index 0000000000000..883a323075faf
--- /dev/null
+++ b/bench/vercel/benchmark-app/package.json
@@ -0,0 +1,14 @@
+{
+ "name": "stats-app",
+ "private": true,
+ "license": "MIT",
+ "dependencies": {
+ "webpack-bundle-analyzer": "^4.6.1",
+ "webpack-stats-plugin": "^1.1.0"
+ },
+ "scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "start": "next start"
+ }
+}
diff --git a/bench/vercel/benchmark-app/pages/index.js b/bench/vercel/benchmark-app/pages/index.js
new file mode 100644
index 0000000000000..7ab1d4cea6d4b
--- /dev/null
+++ b/bench/vercel/benchmark-app/pages/index.js
@@ -0,0 +1,20 @@
+if (!('hot' in Math)) Math.hot = false
+
+export default function page({ hot }) {
+ return `${hot ? 'HOT' : 'COLD'}`
+}
+
+export async function getServerSideProps() {
+ const wasHot = Math.hot
+ Math.hot = true
+
+ return {
+ props: {
+ hot: wasHot,
+ },
+ }
+}
+
+export const config = {
+ runtime: 'experimental-edge',
+}
diff --git a/bench/vercel/chart.js b/bench/vercel/chart.js
new file mode 100644
index 0000000000000..c35e07e9d74ad
--- /dev/null
+++ b/bench/vercel/chart.js
@@ -0,0 +1,99 @@
+import downsampler from 'downsample-lttb'
+import asciichart from 'asciichart'
+import terminalSize from 'term-size'
+
+const CHART_WIDTH = terminalSize().columns - 15 // space for the labels
+
+function getMetrics(data) {
+ const sorted = [...data].sort((a, b) => a - b)
+ const getPercentile = (percentile) => {
+ const index = Math.floor((sorted.length - 1) * percentile)
+ return sorted[index]
+ }
+ return {
+ hits: sorted.length,
+ confidenceInterval: round(getConfidenceInterval(sorted)),
+ median: getPercentile(0.5),
+ avg: sorted.reduce((a, b) => a + b, 0) / sorted.length,
+ p75: getPercentile(0.75),
+ p95: getPercentile(0.95),
+ p99: getPercentile(0.99),
+ p25: getPercentile(0.25),
+ min: sorted[0],
+ max: sorted[sorted.length - 1],
+ }
+}
+
+function round(num) {
+ return Math.round(num * 100) / 100
+}
+
+// thanks Copilot
+function getConfidenceInterval(data) {
+ const n = data.length
+ const m = data.reduce((a, b) => a + b) / n
+ const s = Math.sqrt(
+ data.map((x) => Math.pow(x - m, 2)).reduce((a, b) => a + b) / n
+ )
+ const z = 1.96 // 95% confidence
+ const e = z * (s / Math.sqrt(n))
+ return e
+}
+
+export function downsample(data, maxPoints) {
+ const sortedData = [...data].sort((a, b) => a - b)
+ return downsampler
+ .processData(
+ // the downsampler expects a 2d array of [x, y] values, so we need to add an index
+ sortedData.map((p, i) => [p, i]),
+ maxPoints
+ )
+ .map((p) => p[0])
+}
+
+export function printBenchmarkResults({ origin, head }, metricSelector) {
+ const [processedOriginData, processedHeadData] = [origin, head].map(
+ (results) => results.map(metricSelector).filter(Boolean)
+ )
+
+ const [originMetrics, headMetrics] = [
+ processedOriginData,
+ processedHeadData,
+ ].map(getMetrics)
+
+ const deltaMetrics = {
+ min: headMetrics.min - originMetrics.min,
+ max: headMetrics.max - originMetrics.max,
+ avg: headMetrics.avg - originMetrics.avg,
+ median: headMetrics.median - originMetrics.median,
+ p95: headMetrics.p95 - originMetrics.p95,
+ p99: headMetrics.p99 - originMetrics.p99,
+ p75: headMetrics.p75 - originMetrics.p75,
+ p25: headMetrics.p25 - originMetrics.p25,
+ }
+
+ console.table({
+ origin: originMetrics,
+ head: headMetrics,
+ delta: deltaMetrics,
+ })
+
+ const [originData, headData] = [processedOriginData, processedHeadData].map(
+ (data) =>
+ downsample(
+ data,
+ Math.min(
+ CHART_WIDTH,
+ processedOriginData.length,
+ processedHeadData.length
+ )
+ )
+ )
+
+ console.log(
+ asciichart.plot([originData, headData], {
+ height: 15,
+ colors: [asciichart.blue, asciichart.red],
+ })
+ )
+}
diff --git a/bench/vercel/gen-request.js b/bench/vercel/gen-request.js
new file mode 100644
index 0000000000000..ac99226f55a96
--- /dev/null
+++ b/bench/vercel/gen-request.js
@@ -0,0 +1,41 @@
+import https from 'https'
+import timer from '@szmarczak/http-timer'
+
+// a wrapper around genAsyncRequest that will retry the request 5 times if it fails
+export async function genRetryableRequest(url) {
+ let retries = 0
+ while (retries < 5) {
+ try {
+ return await genAsyncRequest(url)
+ } catch (err) {}
+ retries++
+ await new Promise((r) => setTimeout(r, 1000))
+ }
+ throw new Error(`Failed to fetch ${url}, too many retries`)
+}
+
+// a wrapper around http.request that is enhanced with timing information
+async function genAsyncRequest(url) {
+ return new Promise((resolve, reject) => {
+ const request = https.get(url)
+ timer(request)
+ request.on('response', (response) => {
+ let body = ''
+ response.on('data', (data) => {
+ body += data
+ })
+ response.on('end', () => {
+ resolve({
+ ...response.timings.phases,
+ cold: !body.includes('HOT'),
+ })
+ })
+ response.on('error', (err) => {
+ reject(err)
+ })
+ })
+ request.on('error', (err) => {
+ reject(err)
+ })
+ })
+}
diff --git a/bench/vercel/generate-package-json.js b/bench/vercel/generate-package-json.js
new file mode 100644
index 0000000000000..1d449d460c1ca
--- /dev/null
+++ b/bench/vercel/generate-package-json.js
@@ -0,0 +1,52 @@
+import execa from 'execa'
+import fs from 'fs/promises'
+import path from 'path'
+
+export async function generatePackageJson(folder, withLocalNext = false) {
+ const packageJson = JSON.parse(
+ await fs.readFile(path.join(folder, 'package.json'))
+ )
+
+ const currentVersions = await getCurrentRootReactPackagesVersions()
+
+ packageJson.dependencies = packageJson.dependencies || {}
+ packageJson.dependencies['react'] = currentVersions.react
+ packageJson.dependencies['react-dom'] = currentVersions['react-dom']
+ if (withLocalNext) {
+ packageJson.dependencies.next = await packNextBuild(folder)
+ } else {
+ packageJson.dependencies.next = await getCurrentNextVersion()
+ }
+
+ await fs.writeFile(
+ path.join(folder, 'package.json'),
+ JSON.stringify(packageJson, null, 2)
+ )
+}
+
+export async function packNextBuild(folder) {
+ const process = await execa('npm', [
+ 'pack',
+ '../../packages/next',
+ `--pack-destination=${folder}`,
+ ])
+
+ return `file:./${process.stdout}`
+}
+
+async function getCurrentNextVersion() {
+ const packageJson = JSON.parse(
+ await fs.readFile('../../packages/next/package.json', 'utf8')
+ )
+ return packageJson.version
+}
+
+async function getCurrentRootReactPackagesVersions() {
+ const packageJson = JSON.parse(
+ await fs.readFile('../../package.json', 'utf8')
+ )
+ return {
+ react: packageJson.devDependencies['react-exp'],
+ 'react-dom': packageJson.devDependencies['react-dom-exp'],
+ }
+}
diff --git a/bench/vercel/package.json b/bench/vercel/package.json
new file mode 100644
index 0000000000000..4ce5045df58f6
--- /dev/null
+++ b/bench/vercel/package.json
@@ -0,0 +1,24 @@
+{
+ "name": "bench-production",
+ "version": "1.0.0",
+ "description": "Scripts for benchmarking in production.",
+ "main": "bench.js",
+ "type": "module",
+ "scripts": {
+ "bench": "node bench.js"
+ },
+ "author": "",
+ "license": "ISC",
+ "dependencies": {
+ "@szmarczak/http-timer": "5.0.1",
+ "asciichart": "1.5.25",
+ "commander": "2.20.0",
+ "dotenv": "10.0.0",
+ "downsample-lttb": "0.0.1",
+ "listr2": "5.0.5",
+ "p-queue": "7.3.0",
+ "term-size": "3.0.2",
+ "webpack-bundle-analyzer": "^4.6.1",
+ "webpack-stats-plugin": "^1.1.0"
+ }
+}
diff --git a/bench/vercel/project-utils.js b/bench/vercel/project-utils.js
new file mode 100644
index 0000000000000..6d069dc0a619c
--- /dev/null
+++ b/bench/vercel/project-utils.js
@@ -0,0 +1,218 @@
+import { config } from 'dotenv'
+
+import fetch from 'node-fetch'
+import chalk from 'chalk'
+import execa from 'execa'
+import path from 'path'
+import url from 'url'
+import { generatePackageJson } from './generate-package-json.js'
+import { Listr } from 'listr2'
+
+config()
+
+const TEST_PROJECT_NAME = process.env.VERCEL_TEST_PROJECT_NAME
+const ORIGIN_PROJECT_NAME = TEST_PROJECT_NAME + '-origin'
+const HEAD_PROJECT_NAME = TEST_PROJECT_NAME + '-head'
+
+const TEST_TEAM_NAME = process.env.VERCEL_TEST_TEAM
+const TEST_TOKEN = process.env.VERCEL_TEST_TOKEN
+const VERCEL_EDGE_FUNCTIONS_BRIDGE_PKG =
+ process.env.VERCEL_EDGE_FUNCTIONS_BRIDGE_PKG
+const __dirname = url.fileURLToPath(new URL('.', import.meta.url))
+
+const appFolder = path.join(__dirname, 'benchmark-app')
+const originAppFolder = path.join(__dirname, 'benchmark-app-origin')
+const headAppFolder = path.join(__dirname, 'benchmark-app-head')
+
+export async function generateProjects() {
+ const { originUrl, headUrl } = await new Listr(
+ [
+ {
+ title: 'Origin project',
+ task: (ctx, task) =>
+ task.newListr(
+ (parent) => [
+ {
+ title: 'Resetting project',
+ task: async () => {
+ await resetProject(ORIGIN_PROJECT_NAME)
+ },
+ },
+ {
+ title: 'copying app',
+ task: async () => {
+ await execa('cp', ['-f', '-R', appFolder, originAppFolder])
+ },
+ },
+ {
+ title: 'Set Next.js version in package.json',
+ task: async () => {
+ await generatePackageJson(originAppFolder)
+ },
+ },
+ {
+ title: 'deploying project',
+ task: async () => {
+ const url = await deployProject(
+ ORIGIN_PROJECT_NAME,
+ originAppFolder
+ )
+ ctx.originUrl = url
+ },
+ },
+ ],
+ { concurrent: false }
+ ),
+ },
+ {
+ title: 'Head project',
+ task: (ctx, task) =>
+ task.newListr(
+ (parent) => [
+ {
+ title: 'Resetting project',
+ task: async () => {
+ await resetProject(HEAD_PROJECT_NAME)
+ },
+ },
+ {
+ title: 'copying app',
+ task: async () => {
+ await execa('cp', ['-f', '-R', appFolder, headAppFolder])
+ },
+ },
+ {
+ title: 'pack local Next.js version',
+ task: async () => {
+ await generatePackageJson(headAppFolder, true)
+ },
+ },
+ {
+ title: 'deploying project',
+ task: async () => {
+ const url = await deployProject(
+ HEAD_PROJECT_NAME,
+ headAppFolder
+ )
+ ctx.headUrl = url
+ },
+ },
+ ],
+ { concurrent: false }
+ ),
+ },
+ ],
+ { concurrent: true }
+ ).run()
+
+ return [originUrl, headUrl]
+}
+
+export async function cleanupProjectFolders() {
+ await Promise.all([
+ execa('rm', ['-rf', originAppFolder]),
+ execa('rm', ['-rf', headAppFolder]),
+ ])
+}
+
+async function resetProject(projectName) {
+ const deleteRes = await fetch(
+ `https://vercel.com/api/v8/projects/${encodeURIComponent(
+ projectName
+ )}?teamId=${TEST_TEAM_NAME}`,
+ {
+ method: 'DELETE',
+ headers: {
+ Authorization: `Bearer ${TEST_TOKEN}`,
+ },
+ }
+ )
+
+ if (!deleteRes.ok && deleteRes.status !== 404) {
+ throw new Error(
+ `Failed to delete project got status ${
+ deleteRes.status
+ }, ${await deleteRes.text()}`
+ )
+ }
+
+ const createRes = await fetch(
+ `https://vercel.com/api/v8/projects?teamId=${TEST_TEAM_NAME}`,
+ {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ Authorization: `Bearer ${TEST_TOKEN}`,
+ },
+ body: JSON.stringify({
+ framework: 'nextjs',
+ name: projectName,
+ }),
+ }
+ )
+
+ if (!createRes.ok) {
+ throw new Error(
+ `Failed to create project got status ${
+ createRes.status
+ }, ${await createRes.text()}`
+ )
+ }
+}
+
+export async function deployProject(projectName, appFolder) {
+ try {
+ const vercelFlags = ['--scope', TEST_TEAM_NAME]
+ const vercelEnv = { ...process.env, TOKEN: TEST_TOKEN }
+
+ // link the project
+ const linkRes = await execa(
+ 'vercel',
+ ['link', '-p', projectName, '--confirm', ...vercelFlags],
+ {
+ cwd: appFolder,
+ env: vercelEnv,
+ }
+ )
+
+ if (linkRes.exitCode !== 0) {
+ throw new Error(
+ `Failed to link project ${linkRes.stdout} ${linkRes.stderr} (${linkRes.exitCode})`
+ )
+ }
+
+ const deployRes = await execa(
+ 'vercel',
+ [
+ 'deploy',
+ '--build-env',
+ 'NEXT_PRIVATE_TEST_MODE=1',
+ '--build-env',
+ 'NEXT_TELEMETRY_DISABLED=1',
+ ...(VERCEL_EDGE_FUNCTIONS_BRIDGE_PKG
+ ? [
+ '--build-env',
+ `VERCEL_EDGE_FUNCTIONS_BRIDGE_PKG=${VERCEL_EDGE_FUNCTIONS_BRIDGE_PKG}`,
+ ]
+ : []),
+ '--force',
+ ...vercelFlags,
+ ],
+ {
+ cwd: appFolder,
+ env: vercelEnv,
+ }
+ )
+
+ if (deployRes.exitCode !== 0) {
+ throw new Error(
+ `Failed to deploy project ${linkRes.stdout} ${linkRes.stderr} (${linkRes.exitCode})`
+ )
+ }
+
+ return deployRes.stdout
+ } catch (err) {
+ console.log(chalk.red('Deployment failed: ', err))
+ throw err
+ }
+}
diff --git a/contributing.md b/contributing.md
index 2d9a0da2ddde6..32733ca5e4002 100644
--- a/contributing.md
+++ b/contributing.md
@@ -1,54 +1,33 @@
# Contributing to Next.js
-Our Commitment to Open Source can be found [here](https://zeit.co/blog/oss)
+[Watch the 40-minute walkthrough video on how to contribute to Next.js.](https://www.youtube.com/watch?v=cuoNzXFLitc)
-1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
-1. Install yarn: `npm install -g yarn`
-1. Install the dependencies: `yarn`
-1. Run `yarn run dev` to build and watch for code changes
+- Read about our [Commitment to Open Source](https://vercel.com/oss).
+- Before jumping into a PR be sure to search [existing PRs](https://github.com/vercel/next.js/pulls) or [issues](https://github.com/vercel/next.js/issues) for an open or closed item that relates to your submission.
-## To run tests
+## Repository
-Running all tests:
+- [Triaging](./contributing/repository/triaging.md)
+- [Linting](./contributing/repository/linting.md)
+- [Release Channels and Publishing](./contributing/repository/release-channels-publishing.md)
+- [Pull Request Descriptions](./contributing/repository/pull-request-descriptions.md)
-```
-yarn testonly
-```
+## Documentation
-Running a specific test suite inside of the `test/integration` directory:
+- [Adding Documentation](./contributing/docs/adding-documentation.md)
-```
-yarn testonly --testPathPattern "production"
-```
+## Examples
-Running just one test in the `production` test suite:
+To contribute to [our examples](./examples), please see
-```
-yarn testonly --testPathPattern "production" -t "should allow etag header support"
-```
+- [Adding Examples](./contributing/examples/adding-examples.md)
+- [Run Example Apps](./contributing/examples/run-example-apps.md)
-## Running the integration test apps without running tests
+## Core
-```
-./node_modules/.bin/next ./test/integration/basic
-```
-
-## Testing in your own app
-
-Because of the way Node.js resolves modules the easiest way to test your own application is copying it into the `test` directory.
-
-```
-cp -r yourapp /test/integration/yourapp
-```
-
-Make sure you remove `react` `react-dom` and `next` from `test/integration/yourapp/node_modules` as otherwise they will be overwritten.
-
-```bash
-rm -rf /test/integration/yourapp/{react,react-dom,next,next-server}
-```
-
-Then run your app using:
-
-```
-./node_modules/.bin/next ./test/integration/yourapp
-```
+- [Developing](./contributing/core/developing.md)
+- [Building](./contributing/core/building.md)
+- [Testing](./contributing/core/testing.md)
+- [Adding Error Links](./contributing/core/adding-error-links.md)
+- [Developing Using Local App](./contributing/core/developing-using-local-app.md)
+
diff --git a/contributing/core/adding-error-links.md b/contributing/core/adding-error-links.md
new file mode 100644
index 0000000000000..0f6ccb3d66227
--- /dev/null
+++ b/contributing/core/adding-error-links.md
@@ -0,0 +1,12 @@
+# Adding Warning and Error Descriptions
+
+Next.js has a system to add helpful links to warnings and errors.
+
+This allows the logged message to be short while giving a broader description and instructions on how to solve the warning/error on the documentation.
+
+In general, all warnings and errors added should have these links attached.
+
+Below are the steps to add a new link:
+
+1. Run `pnpm new-error` which will create the error document and update the manifest automatically.
+2. At the end of the command the URL for the error will be provided, add that to your error.
diff --git a/contributing/core/building.md b/contributing/core/building.md
new file mode 100644
index 0000000000000..bce370380cbc8
--- /dev/null
+++ b/contributing/core/building.md
@@ -0,0 +1,13 @@
+# Building
+
+You can build Next.js, including all type definitions and packages, with:
+
+```bash
+pnpm build
+```
+
+By default, the latest canary of the `next-swc` binaries will be installed and used. If you are actively working on Rust code or you need to test out the most recent Rust code that hasn't been published as a canary yet, you can [install Rust](https://www.rust-lang.org/tools/install) and run `pnpm --filter=@next/swc build-native`.
+
+If you want to test out the wasm build locally, you will need to [install wasm-pack](https://rustwasm.github.io/wasm-pack/installer/). Run `pnpm --filter=@next/swc build-wasm --target ` to build and `node ./scripts/setup-wasm.mjs` to copy it into your `node_modules`. Run next with `NODE_OPTIONS='--no-addons'` to force it to use the wasm binary.
+
+If you need to clean the project for any reason, use `pnpm clean`.
diff --git a/contributing/core/developing-using-local-app.md b/contributing/core/developing-using-local-app.md
new file mode 100644
index 0000000000000..bb7a5e51c35f2
--- /dev/null
+++ b/contributing/core/developing-using-local-app.md
@@ -0,0 +1,50 @@
+# Developing Using Your Local Version of Next.js
+
+There are two options to develop with your local version of the codebase:
+
+## Develop inside the monorepo
+
+This will use the version of `next` built inside of the Next.js monorepo. You can also let `pnpm dev` run in a separate terminal. This will let you make changes to Next.js at the same time (note that some changes might require re-running `pnpm next-with-deps` or `pnpm next`).
+
+If your app does not have dependencies, you can create a directory inside the monorepo (eg.: `dev-app`) and run `pnpm next ./dev-app` without creating a `package.json` file.
+
+If you already have an app and it has dependencies, you can follow these steps:
+
+1. Move your app inside of the Next.js monorepo.
+
+2. Run with `pnpm next-with-deps ./app-path-in-monorepo`
+
+## Set as a local dependency in package.json
+
+1. Run `pnpm dev` in the background in the Next.js monorepo.
+
+2. In your app's root directory, run:
+
+ ```sh
+ pnpm add ./path/to/next.js/{packages/next,node_modules/{react,react-dom}}
+ ```
+
+ to re-install all of the dependencies and point `next`, `react` and `react-dom` to the monorepo versions.
+
+ Note that Next.js will be copied from the locally compiled version as opposed to being downloaded from the NPM registry.
+
+3. Run your application as you normally would.
+
+### Troubleshooting
+
+- If you see the below error while running `pnpm dev` with `next`:
+
+```
+Failed to load SWC binary, see more info here: https://nextjs.org/docs/messages/failed-loading-swc
+```
+
+Try to add the below section to your `package.json`, then run again
+
+```json
+"optionalDependencies": {
+ "@next/swc-linux-x64-gnu": "canary",
+ "@next/swc-win32-x64-msvc": "canary",
+ "@next/swc-darwin-x64": "canary",
+ "@next/swc-darwin-arm64": "canary"
+},
+```
diff --git a/contributing/core/developing.md b/contributing/core/developing.md
new file mode 100644
index 0000000000000..3614fe22e96b9
--- /dev/null
+++ b/contributing/core/developing.md
@@ -0,0 +1,44 @@
+# Developing
+
+- The development branch is `canary`.
+- All pull requests should be opened against `canary`.
+- The changes on the `canary` branch are published to the `@canary` tag on npm regularly.
+
+To develop locally:
+
+1. Install the [GitHub CLI](https://github.com/cli/cli#installation).
+1. Clone the Next.js repository:
+ ```
+ gh repo clone vercel/next.js
+ ```
+1. Create a new branch:
+ ```
+ git checkout -b MY_BRANCH_NAME origin/canary
+ ```
+1. Enable pnpm:
+ ```
+ corepack enable pnpm
+ ```
+1. Install the dependencies with:
+ ```
+ pnpm install
+ ```
+1. Start developing and watch for code changes:
+ ```
+ pnpm dev
+ ```
+1. In a new terminal, run `pnpm types` to compile declaration files from
+ TypeScript.
+ _Note: You may need to repeat this step if your types get outdated._
+1. When your changes are finished, commit them to the branch:
+ ```
+ git add .
+ git commit -m "DESCRIBE_YOUR_CHANGES_HERE"
+ ```
+1. To open a pull request you can use the GitHub CLI which automatically forks and sets up a remote branch. Follow the prompts when running:
+ ```
+ gh pr create
+ ```
+
+For instructions on how to build a project with your local version of the CLI,
+see **[Developing Using Your Local Version of Next.js](./developing-using-local-app.md)** as linking the package is not sufficient to develop locally.
diff --git a/contributing/core/testing.md b/contributing/core/testing.md
new file mode 100644
index 0000000000000..ae3e8db7bfd59
--- /dev/null
+++ b/contributing/core/testing.md
@@ -0,0 +1,71 @@
+# Testing
+
+## Running tests
+
+Before you start to run tests, you need to build project first:
+
+```bash
+pnpm build
+```
+
+And for more detail about building, you can check out [building.md](./building.md)
+
+We recommend running the tests in headless mode (with the browser windows hidden) and with a specific directory pattern and/or test name (`-t`) which ensures only a small part of the test suite is run locally:
+
+For example, running one test in the production test suite:
+
+Running one test in the `test/integration/production` test suite:
+
+```sh
+pnpm testheadless test/integration/production/ -t "should allow etag header support"
+```
+
+Running all tests in the `test/integration/production` test suite:
+
+```sh
+pnpm testheadless test/integration/production/
+```
+
+When you want to debug a particular test you can replace `pnpm testheadless` with `pnpm testonly` to opt out of the headless browser.
+When the test runs it will open the browser that is in the background by default, allowing you to inspect what is on the screen.
+
+```sh
+pnpm testonly test/integration/production/ -t "should allow etag header support"
+```
+
+## Writing tests for Next.js
+
+### Getting Started
+
+You can set up a new test using `pnpm new-test` which will start from a template related to the test type.
+
+### Test Types in Next.js
+
+- e2e: Runs against `next dev`, `next start`, and deployed to Vercel.
+- development: Runs against `next dev`.
+- production: Runs against `next start`.
+- integration: Historical location of tests. Runs misc checks and modes. Ideally, we don't add new test suites here anymore as these tests are not isolated from the monorepo.
+- unit: Very fast tests that should run without a browser or run `next` and should be testing a specific utility.
+
+For the e2e, development, and production tests the `createNext` utility should be used and an example is available [here](../../test/e2e/example.txt). This creates an isolated Next.js install to ensure nothing in the monorepo is relied on accidentally causing incorrect tests.
+
+All new test suites should be written in TypeScript either `.ts` (or `.tsx` for unit tests). This will help ensure we catch smaller issues in tests that could cause flakey or incorrect tests.
+
+If a test suite already exists that relates closely to the item being tested (e.g. hash navigation relates to existing navigation test suites) the new checks can be added to the existing test suite.
+
+### Best Practices
+
+- When checking for a condition that might take time, ensure it is waited for either using the browser `waitForElement` or using the `check` util in `next-test-utils`.
+- When applying a fix, ensure the test fails without the fix. This makes sure the test will properly catch regressions.
+
+### Helpful environment variables
+
+Some test-specific environment variables can be used to help debug isolated tests better, these can be leveraged by prefixing the `pnpm test` command.
+
+- When investigating failures in isolated tests you can use `NEXT_TEST_SKIP_CLEANUP=1` to prevent deleting the temp folder created for the test, then you can run `pnpm next` while inside of the temp folder to debug the fully set-up test project.
+- You can also use `NEXT_SKIP_ISOLATE=1` if the test doesn't need to be installed to debug and it will run inside of the Next.js repo instead of the temp directory, this can also reduce test times locally but is not compatible with all tests.
+- The `NEXT_TEST_MODE` env variable allows toggling specific test modes for the `e2e` folder, it can be used when not using `pnpm test-dev` or `pnpm test-start` directly. Valid test modes can be seen here: https://github.com/vercel/next.js/blob/aa664868c102ddc5adc618415162d124503ad12e/test/lib/e2e-utils.ts#L46
+
+### Debugging
+
+When tests are run in CI and a test failure occurs we attempt to capture traces of the playwright run to make debugging the failure easier. A test-trace artifact should be uploaded after the workflow completes which can be downloaded, unzipped, and then inspected with `pnpm playwright show-trace ./path/to/trace`
diff --git a/contributing/core/vscode-debugger.md b/contributing/core/vscode-debugger.md
new file mode 100644
index 0000000000000..d240b0af040bb
--- /dev/null
+++ b/contributing/core/vscode-debugger.md
@@ -0,0 +1,27 @@
+# Using the VS Code Debugger
+
+## Debug configurations
+
+The Next.js monorepo provides configurations in the [`.vscode/launch.json`](../../.vscode/launch.json) file to help you [debug Next.js from VS Code](https://code.visualstudio.com/docs/editor/debugging).
+
+The common configurations are:
+
+- Launch app development: Run `next dev` with an attached debugger
+- Launch app build: Run `next build` with an attached debugger
+- Launch app production: Run `next start` with an attached debugger
+
+### Run a specific app
+
+Any Next.js app inside the monorepo can be debugged with these configurations. For example to run "Launch app development" against `examples/hello-world`:
+
+1. Open the [`.vscode/launch.json`](../../.vscode/launch.json) file.
+2. Find the configuration "Launch app development".
+3. Edit the `runtimeArgs` array's last item to be `"examples/hello-world"`.
+4. Save the file.
+5. Now you can start the debugger and it will run against the `examples/hello-world` app!
+
+To see the changes you make to the Next.js codebase during development, you can run `pnpm dev` in the root directory, which will watch for file changes in `packages/next` and recompile the Next.js source code on any file saves.
+
+## Breakpoints
+
+When developing/debugging Next.js, you can set breakpoints anywhere in the `packages/next` source code that will stop the debugger at certain locations so you can examine the behavior. Read more about [breakpoints in the VS Code documentation](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_breakpoints).
diff --git a/contributing/docs/adding-documentation.md b/contributing/docs/adding-documentation.md
new file mode 100644
index 0000000000000..f89bd836dd565
--- /dev/null
+++ b/contributing/docs/adding-documentation.md
@@ -0,0 +1,40 @@
+# Updating Documentation Paths
+
+Our documentation currently leverages a [manifest file](/docs/manifest.json), which is how documentation entries are checked.
+
+When adding a new entry under an existing category you only need to add an entry with `{title: '', path: '/docs/path/to/file.md'}`. The "title" is what is shown on the sidebar.
+
+When moving the location/url of an entry, the "title" field can be removed from the existing entry and the ".md" extension removed from the "path", then a "redirect" field with the shape of `{permanent: true/false, destination: '/some-url'}` can be added. A new entry should be added with the "title" and "path" fields if the document is renamed within the [`docs` folder](/docs) that points to the new location in the folder, e.g. `/docs/some-url.md`
+
+Example of moving documentation file:
+
+Before:
+
+```json
+[
+ {
+ "path": "/docs/original.md",
+ "title": "Hello world"
+ }
+]
+```
+
+After:
+
+```json
+[
+ {
+ "path": "/docs/original",
+ "redirect": {
+ "permanent": false,
+ "destination": "/new"
+ }
+ }
+ {
+ "path": "/docs/new.md",
+ "title": "Hello world"
+ },
+]
+```
+
+Note: the manifest is checked automatically in the "lint" step in CI when opening a PR.
diff --git a/contributing/examples/adding-examples.md b/contributing/examples/adding-examples.md
new file mode 100644
index 0000000000000..c6f4cebc822ad
--- /dev/null
+++ b/contributing/examples/adding-examples.md
@@ -0,0 +1,57 @@
+## Adding examples
+
+When you add an example to the [examples](examples) directory, please follow these guidelines to ensure high-quality examples:
+
+- TypeScript should be leveraged for new examples (no need for separate JavaScript and TypeScript examples, converting old JavaScript examples is preferred)
+- Examples should not add custom ESLint configuration (we have specific templates for ESLint)
+- If API routes aren't used in an example, they should be omitted
+- If an example exists for a certain library and you would like to showcase a specific feature of that library, the existing example should be updated (instead of adding a new example)
+- Package manager specific config should not be added (e.g. `resolutions` in `package.json`)
+- In `package.json` the version of `next` should be `latest`
+- In `package.json` the dependency versions should be up-to-date
+- Use `export default function` for page components and API Routes instead of `const`/`let` (The exception is if the page has `getInitialProps`, in which case [`NextPage`](https://nextjs.org/docs/api-reference/data-fetching/get-initial-props#typescript) could be useful)
+- CMS example directories should be prefixed with `cms-`
+- Example directories should not be prefixed with `with-`
+- Make sure linting passes (you can run `pnpm lint-fix`)
+
+Also, don’t forget to add a `README.md` file with the following format:
+
+- Replace `DIRECTORY_NAME` with the directory name you’re adding.
+- Fill in `Example Name` and `Description`.
+- Examples should be TypeScript first, if possible.
+- Omit the `name` and `version` fields from your `package.json`.
+- Ensure all your dependencies are up to date.
+- Ensure you’re using [`next/image`](https://nextjs.org/docs/api-reference/next/image).
+- To add additional installation instructions, please add them where appropriate.
+- To add additional notes, add `## Notes` section at the end.
+- Remove the `Deploy your own` section if your example can’t be immediately deployed to Vercel.
+
+````markdown
+# Example Name
+
+Description
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/DIRECTORY_NAME&project-name=DIRECTORY_NAME&repository-name=DIRECTORY_NAME)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
+```
+
+```bash
+yarn create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
+```
+
+```bash
+pnpm create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+````
diff --git a/contributing/examples/run-example-apps.md b/contributing/examples/run-example-apps.md
new file mode 100644
index 0000000000000..c95c20cd35a5c
--- /dev/null
+++ b/contributing/examples/run-example-apps.md
@@ -0,0 +1,22 @@
+# Running Example Apps
+
+Running examples can be done with:
+
+```sh
+pnpm next ./examples/basic-css/
+```
+
+To figure out which pages are available for the given example, you can run:
+
+```sh
+EXAMPLE=./test/integration/basic
+(\
+ cd $EXAMPLE/pages; \
+ find . -type f \
+ | grep -v '\.next' \
+ | sed 's#^\.##' \
+ | sed 's#index\.js##' \
+ | sed 's#\.js$##' \
+ | xargs -I{} echo localhost:3000{} \
+)
+```
diff --git a/contributing/repository/linting.md b/contributing/repository/linting.md
new file mode 100644
index 0000000000000..513797ce7e280
--- /dev/null
+++ b/contributing/repository/linting.md
@@ -0,0 +1,37 @@
+# Linting
+
+The Next.js repository runs [ESLint](https://eslint.org), [Prettier](https://prettier.io) and [alex](https://alexjs.com) to lint and format all code and documentation.
+
+To lint all code you can run:
+
+```sh
+pnpm lint
+```
+
+If you get errors, you can run the ESLint and Prettier auto-fix using:
+
+```sh
+pnpm lint-fix
+```
+
+Not all rules can be auto-fixed, those require manual changes.
+
+If you get a warning by alex, follow the instructions to correct the language.
+
+## ESLint
+
+We recommend installing the [ESLint plugin for VS Code](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint).
+
+You can find the enabled rules in the [ESLint config](../../.eslintrc.json).
+
+## Prettier
+
+We recommend installing the [Prettier plugin for VS Code](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).
+
+You can find the format configuration in the [Prettier config](../../.prettierrc.json).
+
+## alex
+
+We recommend installing the [AlexJS Linter extension for VSCode](https://marketplace.visualstudio.com/items?itemName=TLahmann.alex-linter)
+
+You can find the configuration in the [alex config](../../.alexrc).
diff --git a/contributing/repository/pull-request-descriptions.md b/contributing/repository/pull-request-descriptions.md
new file mode 100644
index 0000000000000..ab217c271b0d4
--- /dev/null
+++ b/contributing/repository/pull-request-descriptions.md
@@ -0,0 +1,7 @@
+# Pull Request Descriptions
+
+Pull Requests opened against the repository have a default template to guide you in creating a descriptive explanation of what the PR is for.
+
+Please make sure to explain the purpose and link any related issues.
+
+Check out the [`pull_request_template.md`](../../.github/pull_request_template.md) for more details.
diff --git a/contributing/repository/release-channels-publishing.md b/contributing/repository/release-channels-publishing.md
new file mode 100644
index 0000000000000..8eb4dce091f43
--- /dev/null
+++ b/contributing/repository/release-channels-publishing.md
@@ -0,0 +1,25 @@
+# Release Channels and Publishing
+
+Next.js has two release channels: `stable` and `canary`.
+
+## Stable
+
+The stable release is what is installed when you `npm install next`. This channel is used by the majority of Next.js users.
+
+This channel is published at a regular cadence and follows [semantic versioning](https://semver.org).
+
+Repository maintainers can publish a new stable version using: `pnpm publish-stable`.
+The command will ask what version to publish `major`, `minor`, or `patch`.
+
+## Canary
+
+The canary channel has to be explicitly installed by users through `npm install next@canary`.
+
+This channel is published early based on the `canary` branch. It holds all changes that are waiting to be published to the stable channel.
+
+`canary` is used to test the latest features and bugfixes on real-world applications.
+
+By installing `next@canary` from time to time you can check if your application is affected by any changes that have not been published yet.
+
+Repository maintainers can publish a new canary version using: `pnpm publish-canary`.
+The command will automatically decide the new version tag as it's an increment from the previous version.
diff --git a/contributing/repository/triaging.md b/contributing/repository/triaging.md
new file mode 100644
index 0000000000000..71eb1636c63fa
--- /dev/null
+++ b/contributing/repository/triaging.md
@@ -0,0 +1,21 @@
+# Triaging
+
+Repository maintainers triage every issue and PR opened in the repository.
+
+Issues are opened with one of these labels:
+
+- `template: story` - a feature request, converted to an [💡 Ideas discussion](https://github.com/vercel/next.js/discussions/categories/ideas)
+- `template: bug` - unverified issue with Next.js itself, or one of the examples in the [`examples`](https://github.com/vercel/next.js/tree/canary/examples) folder
+- `template: documentation` - feedback for improvement or an unverified issue with the Next.js documentation
+
+In the case of a bug report, a maintainer looks at the provided reproduction. If the reproduction is missing or insufficient, a `please add a complete reproduction` label is added. If a reproduction is not provided for more than 30 days, the issue becomes stale and will be automatically closed. If a reproduction is provided within 30 days, the `please add a complete reproduction` label is removed and the issue will not become stale anymore.
+
+Bug reports must be verified against the `next@canary` release. The canary version of Next.js ships daily and includes all features and fixes that have not been released to the stable version yet. Think of canary as a public beta. Some issues may already be fixed in the canary version, so please verify that your issue reproduces before opening a new issue. Issues not verified against `next@canary` will be closed after 30 days.
+
+If the issue is specific to the project and not to Next.js itself, it might be converted to a [🎓️ Help discussion](https://github.com/vercel/next.js/discussions/categories/help)
+
+If the bug is verified, it will receive the `kind: bug` label and will be tracked by the maintainers. An `area:` label can be added to indicate which part of Next.js is affected.
+
+Confirmed issues never become stale or are closed before resolution.
+
+All **closed** PRs and Issues will be locked after 30 days of inactivity (eg.: comment, referencing from elsewhere).
diff --git a/docs/accessibility.md b/docs/accessibility.md
new file mode 100644
index 0000000000000..dc4b4a40ab751
--- /dev/null
+++ b/docs/accessibility.md
@@ -0,0 +1,48 @@
+---
+description: Learn about the built-in accessibility features of Next.js.
+---
+
+# Accessibility
+
+The Next.js team is committed to making Next.js accessible to all developers (and their end-users). By adding accessibility features to Next.js by default, we aim to make the Web more inclusive for everyone.
+
+## Route Announcements
+
+When transitioning between pages rendered on the server (e.g. using the `` tag) screen readers and other assistive technology announce the page title when the page loads so that users understand that the page has changed.
+
+In addition to traditional page navigations, Next.js also supports client-side transitions for improved performance (using `next/link`). To ensure that client-side transitions are also announced to assistive technology, Next.js includes a route announcer by default.
+
+The Next.js route announcer looks for the page name to announce by first inspecting `document.title`, then the `
+
+
+With Next.js you can turn any React page into an AMP page, with minimal config, and without leaving React.
+
+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/api-reference/next/amp.md).
+
+## Caveats
+
+- Only CSS-in-JS is supported. [CSS Modules](/docs/basic-features/built-in-css-support.md) aren't supported by AMP pages at the moment. You can [contribute CSS Modules support to Next.js](https://github.com/vercel/next.js/issues/10549).
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+
diff --git a/docs/advanced-features/amp-support/typescript.md b/docs/advanced-features/amp-support/typescript.md
new file mode 100644
index 0000000000000..2f284c26d8035
--- /dev/null
+++ b/docs/advanced-features/amp-support/typescript.md
@@ -0,0 +1,9 @@
+---
+description: Using AMP with TypeScript? Extend your typings to allow AMP components.
+---
+
+# TypeScript
+
+AMP currently doesn't have built-in types for TypeScript, but it's in their roadmap ([#13791](https://github.com/ampproject/amphtml/issues/13791)).
+
+As a workaround you can manually create a file called `amp.d.ts` inside your project and add these [custom types](https://stackoverflow.com/a/50601125).
diff --git a/docs/advanced-features/automatic-static-optimization.md b/docs/advanced-features/automatic-static-optimization.md
new file mode 100644
index 0000000000000..cbbfbbf756b30
--- /dev/null
+++ b/docs/advanced-features/automatic-static-optimization.md
@@ -0,0 +1,49 @@
+---
+description: Next.js automatically optimizes your app to be static HTML whenever possible. Learn how it works here.
+---
+
+# Automatic Static Optimization
+
+Next.js automatically determines that a page is static (can be prerendered) if it has no blocking data requirements. This determination is made by the absence of `getServerSideProps` and `getInitialProps` in the page.
+
+This feature allows Next.js to emit hybrid applications that contain **both server-rendered and statically generated pages**.
+
+> Statically generated pages are still reactive: Next.js will hydrate your application client-side to give it full interactivity.
+
+One of the main benefits of this feature is that optimized pages require no server-side computation, and can be instantly streamed to the end-user from multiple CDN locations. The result is an _ultra fast_ loading experience for your users.
+
+## How it works
+
+If `getServerSideProps` or `getInitialProps` is present in a page, Next.js will switch to render the page on-demand, per-request (meaning [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering)).
+
+If the above is not the case, Next.js will **statically optimize** your page automatically by prerendering the page to static HTML.
+
+During prerendering, the router's `query` object will be empty since we do not have `query` information to provide during this phase. After hydration, Next.js will trigger an update to your application to provide the route parameters in the `query` object.
+
+The cases where the query will be updated after hydration triggering another render are:
+
+- The page is a [dynamic-route](/docs/routing/dynamic-routes.md).
+- The page has query values in the URL.
+- [Rewrites](/docs/api-reference/next.config.js/rewrites.md) are configured in your `next.config.js` since these can have parameters that may need to be parsed and provided in the `query`.
+
+To be able to distinguish if the query is fully updated and ready for use, you can leverage the `isReady` field on [`next/router`](/docs/api-reference/next/router.md#router-object).
+
+> **Note:** Parameters added with [dynamic routes](/docs/routing/dynamic-routes.md) to a page that's using [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) will always be available inside the `query` object.
+
+`next build` will emit `.html` files for statically optimized pages. For example, the result for the page `pages/about.js` would be:
+
+```bash
+.next/server/pages/about.html
+```
+
+And if you add `getServerSideProps` to the page, it will then be JavaScript, like so:
+
+```bash
+.next/server/pages/about.js
+```
+
+## Caveats
+
+- If you have a [custom `App`](/docs/advanced-features/custom-app.md) with `getInitialProps` then this optimization will be turned off in pages without [Static Generation](/docs/basic-features/data-fetching/get-static-props.md).
+- If you have a [custom `Document`](/docs/advanced-features/custom-document.md) with `getInitialProps` be sure you check if `ctx.req` is defined before assuming the page is server-side rendered. `ctx.req` will be `undefined` for pages that are prerendered.
+- Avoid using the `asPath` value on [`next/router`](/docs/api-reference/next/router.md#router-object) in the rendering tree until the router's `isReady` field is `true`. Statically optimized pages only know `asPath` on the client and not the server, so using it as a prop may lead to mismatch errors. The [`active-class-name` example](https://github.com/vercel/next.js/tree/canary/examples/active-class-name) demonstrates one way to use `asPath` as a prop.
diff --git a/docs/advanced-features/ci-build-caching.md b/docs/advanced-features/ci-build-caching.md
new file mode 100644
index 0000000000000..c7692af86f76b
--- /dev/null
+++ b/docs/advanced-features/ci-build-caching.md
@@ -0,0 +1,129 @@
+---
+description: Learn how to configure CI to cache Next.js builds
+---
+
+# Continuous Integration (CI) Build Caching
+
+To improve build performance, Next.js saves a cache to `.next/cache` that is shared between builds.
+
+To take advantage of this cache in Continuous Integration (CI) environments, your CI workflow will need to be configured to correctly persist the cache between builds.
+
+> If your CI is not configured to persist `.next/cache` between builds, you may see a [No Cache Detected](https://nextjs.org/docs/messages/no-cache) error.
+
+Here are some example cache configurations for common CI providers:
+
+## Vercel
+
+Next.js caching is automatically configured for you. There's no action required on your part.
+
+## CircleCI
+
+Edit your `save_cache` step in `.circleci/config.yml` to include `.next/cache`:
+
+```yaml
+steps:
+ - save_cache:
+ key: dependency-cache-{{ checksum "yarn.lock" }}
+ paths:
+ - ./node_modules
+ - ./.next/cache
+```
+
+If you do not have a `save_cache` key, please follow CircleCI's [documentation on setting up build caching](https://circleci.com/docs/2.0/caching/).
+
+## Travis CI
+
+Add or merge the following into your `.travis.yml`:
+
+```yaml
+cache:
+ directories:
+ - $HOME/.cache/yarn
+ - node_modules
+ - .next/cache
+```
+
+## GitLab CI
+
+Add or merge the following into your `.gitlab-ci.yml`:
+
+```yaml
+cache:
+ key: ${CI_COMMIT_REF_SLUG}
+ paths:
+ - node_modules/
+ - .next/cache/
+```
+
+## Netlify CI
+
+Use [Netlify Plugins](https://www.netlify.com/products/build/plugins/) with [`@netlify/plugin-nextjs`](https://www.npmjs.com/package/@netlify/plugin-nextjs).
+
+## AWS CodeBuild
+
+Add (or merge in) the following to your `buildspec.yml`:
+
+```yaml
+cache:
+ paths:
+ - 'node_modules/**/*' # Cache `node_modules` for faster `yarn` or `npm i`
+ - '.next/cache/**/*' # Cache Next.js for faster application rebuilds
+```
+
+## GitHub Actions
+
+Using GitHub's [actions/cache](https://github.com/actions/cache), add the following step in your workflow file:
+
+```yaml
+uses: actions/cache@v3
+with:
+ # See here for caching with `yarn` https://github.com/actions/cache/blob/main/examples.md#node---yarn or you can leverage caching with actions/setup-node https://github.com/actions/setup-node
+ path: |
+ ~/.npm
+ ${{ github.workspace }}/.next/cache
+ # Generate a new cache whenever packages or source files change.
+ key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
+ # If source files changed but packages didn't, rebuild from a prior cache.
+ restore-keys: |
+ ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
+```
+
+## Bitbucket Pipelines
+
+Add or merge the following into your `bitbucket-pipelines.yml` at the top level (same level as `pipelines`):
+
+```yaml
+definitions:
+ caches:
+ nextcache: .next/cache
+```
+
+Then reference it in the `caches` section of your pipeline's `step`:
+
+```yaml
+- step:
+ name: your_step_name
+ caches:
+ - node
+ - nextcache
+```
+
+## Heroku
+
+Using Heroku's [custom cache](https://devcenter.heroku.com/articles/nodejs-support#custom-caching), add a `cacheDirectories` array in your top-level package.json:
+
+```javascript
+"cacheDirectories": [".next/cache"]
+```
+
+## Azure Pipelines
+
+Using Azure Pipelines' [Cache task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/cache), add the following task to your pipeline yaml file somewhere prior to the task that executes `next build`:
+
+```yaml
+- task: Cache@2
+ displayName: 'Cache .next/cache'
+ inputs:
+ key: next | $(Agent.OS) | yarn.lock
+ path: '$(System.DefaultWorkingDirectory)/.next/cache'
+```
diff --git a/docs/advanced-features/codemods.md b/docs/advanced-features/codemods.md
new file mode 100644
index 0000000000000..dfe8d18657c79
--- /dev/null
+++ b/docs/advanced-features/codemods.md
@@ -0,0 +1,349 @@
+---
+description: Use codemods to update your codebase when upgrading Next.js to the latest version
+---
+
+# Next.js Codemods
+
+Next.js provides Codemod transformations to help upgrade your Next.js codebase when a feature is deprecated.
+
+Codemods are transformations that run on your codebase programmatically. This allows for a large amount of changes to be applied without having to manually go through every file.
+
+## Usage
+
+`npx @next/codemod@latest `
+
+- `transform` - name of transform, see available transforms below.
+- `path` - files or directory to transform
+- `--dry` Do a dry-run, no code will be edited
+- `--print` Prints the changed output for comparison
+
+## Next.js 13
+
+### `new-link`
+
+Safely removes `` from `next/link` or adds `legacyBehavior` prop.
+
+For example:
+
+```jsx
+export default function Page() {
+ return (
+
+ About Us
+
+ )
+}
+```
+
+Transforms into:
+
+```jsx
+export default function Page() {
+ return About Us
+}
+```
+
+### `next-image-to-legacy-image`
+
+This codemod safely migrates existing Next.js 10, 11, 12 applications importing `next/image` to the renamed `next/legacy/image` import in Next.js 13.
+
+For example:
+
+```jsx
+import Image1 from 'next/image'
+import Image2 from 'next/future/image'
+
+export default function Home() {
+ return (
+
+
+
+
+ )
+}
+```
+
+Transforms into:
+
+```jsx
+import Image1 from 'next/legacy/image'
+import Image2 from 'next/image'
+
+export default function Home() {
+ return (
+
+
+
+
+ )
+}
+```
+
+### `next-image-experimental` (experimental)
+
+This codemod dangerously migrates from `next/legacy/image` to the new `next/image` by adding inline styles and removing unused props. Please note this codemod is experimental and only covers static usage (such as ``) but not dynamic usage (such as ``).
+
+- Removes `layout` prop and adds `style`
+- Removes `objectFit` prop and adds `style`
+- Removes `objectPosition` prop and adds `style`
+- Removes `lazyBoundary` prop
+- Removes `lazyRoot` prop
+- Changes next.config.js `loader` to "custom", removes `path`, and sets `loaderFile` to a new file.
+
+#### Before: intrinsic
+
+```jsx
+import Image from 'next/image'
+import img from '../img.png'
+
+function Page() {
+ return
+}
+```
+
+#### After: intrinsic
+
+```jsx
+import Image from 'next/image'
+import img from '../img.png'
+
+const css = { maxWidth: '100%', height: 'auto' }
+function Page() {
+ return
+}
+```
+
+#### Before: responsive
+
+```jsx
+import Image from 'next/image'
+import img from '../img.png'
+
+function Page() {
+ return
+}
+```
+
+#### After: responsive
+
+```jsx
+import Image from 'next/image'
+import img from '../img.png'
+
+const css = { width: '100%', height: 'auto' }
+function Page() {
+ return
+}
+```
+
+#### Before: fill
+
+```jsx
+import Image from 'next/image'
+import img from '../img.png'
+
+function Page() {
+ return
+}
+```
+
+#### After: fill
+
+```jsx
+import Image from 'next/image'
+import img from '../img.png'
+
+function Page() {
+ return
+}
+```
+
+#### Before: fixed
+
+```jsx
+import Image from 'next/image'
+import img from '../img.png'
+
+function Page() {
+ return
+}
+```
+
+#### After: fixed
+
+```jsx
+import Image from 'next/image'
+import img from '../img.png'
+
+function Page() {
+ return
+}
+```
+
+## Next.js 11
+
+### `cra-to-next` (experimental)
+
+Migrates a Create React App project to Next.js; creating a pages directory and necessary config to match behavior. Client-side only rendering is leveraged initially to prevent breaking compatibility due to `window` usage during SSR and can be enabled seamlessly to allow gradual adoption of Next.js specific features.
+
+Please share any feedback related to this transform [in this discussion](https://github.com/vercel/next.js/discussions/25858).
+
+## Next.js 10
+
+### `add-missing-react-import`
+
+Transforms files that do not import `React` to include the import in order for the new [React JSX transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) to work.
+
+For example:
+
+```jsx
+// my-component.js
+export default class Home extends React.Component {
+ render() {
+ return
Hello World
+ }
+}
+```
+
+Transforms into:
+
+```jsx
+// my-component.js
+import React from 'react'
+export default class Home extends React.Component {
+ render() {
+ return
Hello World
+ }
+}
+```
+
+## Next.js 9
+
+### `name-default-component`
+
+Transforms anonymous components into named components to make sure they work with [Fast Refresh](https://nextjs.org/blog/next-9-4#fast-refresh).
+
+For example:
+
+```jsx
+// my-component.js
+export default function () {
+ return
+}
+```
+
+The component will have a camel cased name based on the name of the file, and it also works with arrow functions.
+
+#### Usage
+
+Go to your project
+
+```
+cd path-to-your-project/
+```
+
+Run the codemod:
+
+```
+npx @next/codemod@latest name-default-component
+```
+
+### `withamp-to-config`
+
+Transforms the `withAmp` HOC into Next.js 9 page configuration.
+
+For example:
+
+```js
+// Before
+import { withAmp } from 'next/amp'
+
+function Home() {
+ return
My AMP Page
+}
+
+export default withAmp(Home)
+```
+
+```js
+// After
+export default function Home() {
+ return
My AMP Page
+}
+
+export const config = {
+ amp: true,
+}
+```
+
+#### Usage
+
+Go to your project
+
+```
+cd path-to-your-project/
+```
+
+Run the codemod:
+
+```
+npx @next/codemod@latest withamp-to-config
+```
+
+## Next.js 6
+
+### `url-to-withrouter`
+
+Transforms the deprecated automatically injected `url` property on top level pages to using `withRouter` and the `router` property it injects. Read more here: [https://nextjs.org/docs/messages/url-deprecated](https://nextjs.org/docs/messages/url-deprecated)
+
+For example:
+
+```js
+// From
+import React from 'react'
+export default class extends React.Component {
+ render() {
+ const { pathname } = this.props.url
+ return
Current pathname: {pathname}
+ }
+}
+```
+
+```js
+// To
+import React from 'react'
+import { withRouter } from 'next/router'
+export default withRouter(
+ class extends React.Component {
+ render() {
+ const { pathname } = this.props.router
+ return
Current pathname: {pathname}
+ }
+ }
+)
+```
+
+This is one case. All the cases that are transformed (and tested) can be found in the [`__testfixtures__` directory](https://github.com/vercel/next.js/tree/canary/packages/next-codemod/transforms/__testfixtures__/url-to-withrouter).
+
+#### Usage
+
+Go to your project
+
+```
+cd path-to-your-project/
+```
+
+Run the codemod:
+
+```
+npx @next/codemod@latest url-to-withrouter
+```
diff --git a/docs/advanced-features/compiler.md b/docs/advanced-features/compiler.md
new file mode 100644
index 0000000000000..9a7cbd75a5690
--- /dev/null
+++ b/docs/advanced-features/compiler.md
@@ -0,0 +1,417 @@
+---
+description: Learn about the Next.js Compiler, written in Rust, which transforms and minifies your Next.js application.
+---
+
+# Next.js Compiler
+
+
+ Version History
+
+| Version | Changes |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `v13.0.0` | SWC Minifier enabled by default. |
+| `v12.3.0` | SWC Minifier [stable](https://nextjs.org/blog/next-12-3#swc-minifier-stable). |
+| `v12.2.0` | [SWC Plugins](#swc-plugins-Experimental) experimental support added. |
+| `v12.1.0` | Added support for Styled Components, Jest, Relay, Remove React Properties, Legacy Decorators, Remove Console, and jsxImportSource. |
+| `v12.0.0` | Next.js Compiler [introduced](https://nextjs.org/blog/next-12). |
+
+
+
+The Next.js Compiler, written in Rust using [SWC](http://swc.rs/), allows Next.js to transform and minify your JavaScript code for production. This replaces Babel for individual files and Terser for minifying output bundles.
+
+Compilation using the Next.js Compiler is 17x faster than Babel and enabled by default since Next.js version 12. If you have an existing Babel configuration or are using [unsupported features](#unsupported-features), your application will opt-out of the Next.js Compiler and continue using Babel.
+
+## Why SWC?
+
+[SWC](http://swc.rs/) is an extensible Rust-based platform for the next generation of fast developer tools.
+
+SWC can be used for compilation, minification, bundling, and more – and is designed to be extended. It's something you can call to perform code transformations (either built-in or custom). Running those transformations happens through higher-level tools like Next.js.
+
+We chose to build on SWC for a few reasons:
+
+- **Extensibility:** SWC can be used as a Crate inside Next.js, without having to fork the library or workaround design constraints.
+- **Performance:** We were able to achieve ~3x faster Fast Refresh and ~5x faster builds in Next.js by switching to SWC, with more room for optimization still in progress.
+- **WebAssembly:** Rust's support for WASM is essential for supporting all possible platforms and taking Next.js development everywhere.
+- **Community:** The Rust community and ecosystem are amazing and still growing.
+
+## Supported Features
+
+### Styled Components
+
+We're working to port `babel-plugin-styled-components` to the Next.js Compiler.
+
+First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `next.config.js` file:
+
+```js
+module.exports = {
+ compiler: {
+ // see https://styled-components.com/docs/tooling#babel-plugin for more info on the options.
+ styledComponents: boolean | {
+ // Enabled by default in development, disabled in production to reduce file size,
+ // setting this will override the default for all environments.
+ displayName?: boolean,
+ // Enabled by default.
+ ssr?: boolean,
+ // Enabled by default.
+ fileName?: boolean,
+ // Empty by default.
+ topLevelImportPaths?: string[],
+ // Defaults to ["index"].
+ meaninglessFileNames?: string[],
+ // Enabled by default.
+ cssProp?: boolean,
+ // Empty by default.
+ namespace?: string,
+ // Not supported yet.
+ minify?: boolean,
+ // Not supported yet.
+ transpileTemplateLiterals?: boolean,
+ // Not supported yet.
+ pure?: boolean,
+ },
+ },
+}
+```
+
+`minify`, `transpileTemplateLiterals` and `pure` are not yet implemented. You can follow the progress [here](https://github.com/vercel/next.js/issues/30802). `ssr` and `displayName` transforms are the main requirement for using `styled-components` in Next.js.
+
+### Jest
+
+Jest support not only includes the transformation previously provided by Babel, but also simplifies configuring Jest together with Next.js including:
+
+- Auto mocking of `.css`, `.module.css` (and their `.scss` variants), and image imports
+- Automatically sets up `transform` using SWC
+- Loading `.env` (and all variants) into `process.env`
+- Ignores `node_modules` from test resolving and transforms
+- Ignoring `.next` from test resolving
+- Loads `next.config.js` for flags that enable experimental SWC transforms
+
+First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jest.config.js` file:
+
+```js
+// jest.config.js
+const nextJest = require('next/jest')
+
+// Providing the path to your Next.js app which will enable loading next.config.js and .env files
+const createJestConfig = nextJest({ dir: './' })
+
+// Any custom config you want to pass to Jest
+const customJestConfig = {
+ setupFilesAfterEnv: ['/jest.setup.js'],
+}
+
+// createJestConfig is exported in this way to ensure that next/jest can load the Next.js configuration, which is async
+module.exports = createJestConfig(customJestConfig)
+```
+
+### Relay
+
+To enable [Relay](https://relay.dev/) support:
+
+```js
+// next.config.js
+module.exports = {
+ compiler: {
+ relay: {
+ // This should match relay.config.js
+ src: './',
+ artifactDirectory: './__generated__',
+ language: 'typescript',
+ },
+ },
+}
+```
+
+NOTE: In Next.js all JavaScript files in `pages` directory are considered routes. So, for `relay-compiler` you'll need to specify `artifactDirectory` configuration settings outside of the `pages`, otherwise `relay-compiler` will generate files next to the source file in the `__generated__` directory, and this file will be considered a route, which will break production builds.
+
+### Remove React Properties
+
+Allows to remove JSX properties. This is often used for testing. Similar to `babel-plugin-react-remove-properties`.
+
+To remove properties matching the default regex `^data-test`:
+
+```js
+// next.config.js
+module.exports = {
+ compiler: {
+ reactRemoveProperties: true,
+ },
+}
+```
+
+To remove custom properties:
+
+```js
+// next.config.js
+module.exports = {
+ compiler: {
+ // The regexes defined here are processed in Rust so the syntax is different from
+ // JavaScript `RegExp`s. See https://docs.rs/regex.
+ reactRemoveProperties: { properties: ['^data-custom$'] },
+ },
+}
+```
+
+### Remove Console
+
+This transform allows for removing all `console.*` calls in application code (not `node_modules`). Similar to `babel-plugin-transform-remove-console`.
+
+Remove all `console.*` calls:
+
+```js
+// next.config.js
+module.exports = {
+ compiler: {
+ removeConsole: true,
+ },
+}
+```
+
+Remove `console.*` output except `console.error`:
+
+```js
+// next.config.js
+module.exports = {
+ compiler: {
+ removeConsole: {
+ exclude: ['error'],
+ },
+ },
+}
+```
+
+### Legacy Decorators
+
+Next.js will automatically detect `experimentalDecorators` in `jsconfig.json` or `tsconfig.json`. Legacy decorators are commonly used with older versions of libraries like `mobx`.
+
+This flag is only supported for compatibility with existing applications. We do not recommend using legacy decorators in new applications.
+
+First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jsconfig.json` or `tsconfig.json` file:
+
+```js
+{
+ "compilerOptions": {
+ "experimentalDecorators": true
+ }
+}
+```
+
+### importSource
+
+Next.js will automatically detect `jsxImportSource` in `jsconfig.json` or `tsconfig.json` and apply that. This is commonly used with libraries like [Theme UI](https://theme-ui.com).
+
+First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jsconfig.json` or `tsconfig.json` file:
+
+```js
+{
+ "compilerOptions": {
+ "jsxImportSource": "theme-ui"
+ }
+}
+```
+
+### Emotion
+
+We're working to port `@emotion/babel-plugin` to the Next.js Compiler.
+
+First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `next.config.js` file:
+
+```js
+// next.config.js
+
+module.exports = {
+ compiler: {
+ emotion: boolean | {
+ // default is true. It will be disabled when build type is production.
+ sourceMap?: boolean,
+ // default is 'dev-only'.
+ autoLabel?: 'never' | 'dev-only' | 'always',
+ // default is '[local]'.
+ // Allowed values: `[local]` `[filename]` and `[dirname]`
+ // This option only works when autoLabel is set to 'dev-only' or 'always'.
+ // It allows you to define the format of the resulting label.
+ // The format is defined via string where variable parts are enclosed in square brackets [].
+ // For example labelFormat: "my-classname--[local]", where [local] will be replaced with the name of the variable the result is assigned to.
+ labelFormat?: string,
+ // default is undefined.
+ // This option allows you to tell the compiler what imports it should
+ // look at to determine what it should transform so if you re-export
+ // Emotion's exports, you can still use transforms.
+ importMap?: {
+ [packageName: string]: {
+ [exportName: string]: {
+ canonicalImport?: [string, string],
+ styledBaseImport?: [string, string],
+ }
+ }
+ },
+ },
+ },
+}
+```
+
+### Minification
+
+Next.js' swc compiler is used for minification by default since v13. This is 7x faster than Terser.
+
+If Terser is still needed for any reason this can be configured.
+
+```js
+// next.config.js
+
+module.exports = {
+ swcMinify: false,
+}
+```
+
+## Experimental Features
+
+### Minifier debug options
+
+While the minifier is experimental, we are making the following options available for debugging purposes. They will not be available once the minifier is made stable.
+
+```js
+// next.config.js
+
+module.exports = {
+ experimental: {
+ swcMinifyDebugOptions: {
+ compress: {
+ defaults: true,
+ side_effects: false,
+ },
+ },
+ },
+}
+```
+
+If your app works with the options above, it means `side_effects` is the problematic option.
+See [the SWC documentation](https://swc.rs/docs/configuration/minification#jscminifycompress) for detailed options.
+
+### Modularize Imports
+
+Allows to modularize imports, similar to [babel-plugin-transform-imports](https://www.npmjs.com/package/babel-plugin-transform-imports).
+
+Transforms member style imports:
+
+```js
+import { Row, Grid as MyGrid } from 'react-bootstrap'
+import { merge } from 'lodash'
+```
+
+...into default style imports:
+
+```js
+import Row from 'react-bootstrap/lib/Row'
+import MyGrid from 'react-bootstrap/lib/Grid'
+import merge from 'lodash/merge'
+```
+
+Config for the above transform:
+
+```js
+// next.config.js
+module.exports = {
+ experimental: {
+ modularizeImports: {
+ 'react-bootstrap': {
+ transform: 'react-bootstrap/lib/{{member}}',
+ },
+ lodash: {
+ transform: 'lodash/{{member}}',
+ },
+ },
+ },
+}
+```
+
+Advanced transformations:
+
+- Using regular expressions
+
+Similar to `babel-plugin-transform-imports`, but the transform is templated with [handlebars](https://docs.rs/handlebars) and regular expressions are in Rust [regex](https://docs.rs/regex/latest/regex/) crate's syntax.
+
+The config:
+
+```js
+// next.config.js
+module.exports = {
+ experimental: {
+ modularizeImports: {
+ 'my-library/?(((\\w*)?/?)*)': {
+ transform: 'my-library/{{ matches.[1] }}/{{member}}',
+ },
+ },
+ },
+}
+```
+
+Cause this code:
+
+```js
+import { MyModule } from 'my-library'
+import { App } from 'my-library/components'
+import { Header, Footer } from 'my-library/components/App'
+```
+
+To become:
+
+```js
+import MyModule from 'my-library/MyModule'
+import App from 'my-library/components/App'
+import Header from 'my-library/components/App/Header'
+import Footer from 'my-library/components/App/Footer'
+```
+
+- Handlebars templating
+
+This transform uses [handlebars](https://docs.rs/handlebars) to template the replacement import path in the `transform` field. These variables and helper functions are available:
+
+1. `matches`: Has type `string[]`. All groups matched by the regular expression. `matches.[0]` is the full match.
+2. `member`: Has type `string`. The name of the member import.
+3. `lowerCase`, `upperCase`, `camelCase`, `kebabCase`: Helper functions to convert a string to lower, upper, camel or kebab cases.
+
+### SWC Trace profiling
+
+You can generate SWC's internal transform traces as chromium's [trace event format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview?mode=html#%21=).
+
+```js
+// next.config.js
+
+module.exports = {
+ experimental: {
+ swcTraceProfiling: true,
+ },
+}
+```
+
+Once enabled, swc will generate trace named as `swc-trace-profile-${timestamp}.json` under `.next/`. Chromium's trace viewer (chrome://tracing/, https://ui.perfetto.dev/), or compatible flamegraph viewer (https://www.speedscope.app/) can load & visualize generated traces.
+
+### SWC Plugins (Experimental)
+
+You can configure swc's transform to use SWC's experimental plugin support written in wasm to customize transformation behavior.
+
+```js
+// next.config.js
+
+module.exports = {
+ experimental: {
+ swcPlugins: [
+ [
+ 'plugin',
+ {
+ ...pluginOptions,
+ },
+ ],
+ ],
+ },
+}
+```
+
+`swcPlugins` accepts an array of tuples for configuring plugins. A tuple for the plugin contains the path to the plugin and an object for plugin configuration. The path to the plugin can be an npm module package name or an absolute path to the `.wasm` binary itself.
+
+## Unsupported Features
+
+When your application has a `.babelrc` file, Next.js will automatically fall back to using Babel for transforming individual files. This ensures backwards compatibility with existing applications that leverage custom Babel plugins.
+
+If you're using a custom Babel setup, [please share your configuration](https://github.com/vercel/next.js/discussions/30174). We're working to port as many commonly used Babel transformations as possible, as well as supporting plugins in the future.
diff --git a/docs/advanced-features/custom-app.md b/docs/advanced-features/custom-app.md
new file mode 100644
index 0000000000000..ff0a47cf88d17
--- /dev/null
+++ b/docs/advanced-features/custom-app.md
@@ -0,0 +1,60 @@
+---
+description: Control page initialization and add a layout that persists for all pages by overriding the default App component used by Next.js.
+---
+
+# Custom `App`
+
+> **Note**: Next.js 13 introduces the `app/` directory (beta). This new directory has support for layouts, nested routes, and uses Server Components by default. Inside `app/`, you can fetch data for your entire application inside layouts, including support for more granular nested layouts (with [colocated data fetching](https://beta.nextjs.org/docs/data-fetching/fundamentals)).
+>
+> [Learn more about incrementally adopting `app/`](https://beta.nextjs.org/docs/upgrade-guide).
+
+Next.js uses the `App` component to initialize pages. You can override it and control the page initialization and:
+
+- Persist layouts between page changes
+- Keeping state when navigating pages
+- Custom error handling using `componentDidCatch`
+- Inject additional data into pages
+- [Add global CSS](/docs/basic-features/built-in-css-support.md#adding-a-global-stylesheet)
+
+To override the default `App`, create the file `./pages/_app.js` as shown below:
+
+```jsx
+export default function MyApp({ Component, pageProps }) {
+ return
+}
+```
+
+The `Component` prop is the active `page`, so whenever you navigate between routes, `Component` will change to the new `page`. Therefore, any props you send to `Component` will be received by the `page`.
+
+`pageProps` is an object with the initial props that were preloaded for your page by one of our [data fetching methods](/docs/basic-features/data-fetching/overview.md), otherwise it's an empty object.
+
+The `App.getInitialProps` receives a single argument called `context.ctx`. It's an object with the same set of properties as the [`context` object](/docs/api-reference/data-fetching/get-initial-props#context-object) in `getInitialProps`.
+
+### Caveats
+
+- If your app is running and you added a custom `App`, you'll need to restart the development server. Only required if `pages/_app.js` didn't exist before.
+- Adding a custom [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md) in your `App` will disable [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) in pages without [Static Generation](/docs/basic-features/data-fetching/get-static-props.md).
+- When you add `getInitialProps` in your custom app, you must `import App from "next/app"`, call `App.getInitialProps(appContext)` inside `getInitialProps` and merge the returned object into the return value.
+- `App` does not support Next.js [Data Fetching methods](/docs/basic-features/data-fetching/overview.md) like [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) or [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md). If you need global data fetching, consider [incrementally adopting the `app/` directory](https://beta.nextjs.org/docs/upgrade-guide).
+
+### TypeScript
+
+If you’re using TypeScript, take a look at [our TypeScript documentation](/docs/basic-features/typescript.md#custom-app).
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+
diff --git a/docs/advanced-features/custom-document.md b/docs/advanced-features/custom-document.md
new file mode 100644
index 0000000000000..07f148a7d2972
--- /dev/null
+++ b/docs/advanced-features/custom-document.md
@@ -0,0 +1,117 @@
+---
+description: Extend the default document markup added by Next.js.
+---
+
+# Custom `Document`
+
+> **Note**: Next.js 13 introduces the `app/` directory (beta). This new directory has support for layouts, nested routes, and uses Server Components by default. Inside `app/`, you can modify the initial `html` and `body` tags using a root layout.
+>
+> [Learn more about incrementally adopting `app/`](https://beta.nextjs.org/docs/upgrade-guide).
+
+A custom `Document` can update the `` and `` tags used to render a [Page](/docs/basic-features/pages.md). This file is only rendered on the server, so event handlers like `onClick` cannot be used in `_document`.
+
+To override the default `Document`, create the file `pages/_document.js` as shown below:
+
+```jsx
+import { Html, Head, Main, NextScript } from 'next/document'
+
+export default function Document() {
+ return (
+
+
+
+
+
+
+
+ )
+}
+```
+
+The code above is the default `Document` added by Next.js. Custom attributes are allowed as props. For example, we might want to add `lang="en"` to the `` tag:
+
+```jsx
+
+```
+
+Or add a `className` to the `body` tag:
+
+```jsx
+
+```
+
+``, ``, `` and `` are required for the page to be properly rendered.
+
+## Caveats
+
+- The `` component used in `_document` is not the same as [`next/head`](/docs/api-reference/next/head.md). The `
` component used here should only be used for any `` code that is common for all pages. For all other cases, such as `` tags, we recommend using [`next/head`](/docs/api-reference/next/head.md) in your pages or components.
+- React components outside of `<Main />` will not be initialized by the browser. Do _not_ add application logic here or custom CSS (like `styled-jsx`). If you need shared components in all your pages (like a menu or a toolbar), read [Layouts](/docs/basic-features/layouts.md) instead.
+- `Document` currently does not support Next.js [Data Fetching methods](/docs/basic-features/data-fetching/overview.md) like [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) or [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md).
+
+## Customizing `renderPage`
+
+> **Note:** This is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in `styled-jsx` support.
+
+For [React 18](/docs/advanced-features/react-18.md) support, we recommend avoiding customizing `getInitialProps` and `renderPage`, if possible.
+
+The `ctx` object shown below is equivalent to the one received in [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md#context-object), with the addition of `renderPage`.
+
+```jsx
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+ static async getInitialProps(ctx) {
+ const originalRenderPage = ctx.renderPage
+
+ // Run the React rendering logic synchronously
+ ctx.renderPage = () =>
+ originalRenderPage({
+ // Useful for wrapping the whole react tree
+ enhanceApp: (App) => App,
+ // Useful for wrapping in a per-page basis
+ enhanceComponent: (Component) => Component,
+ })
+
+ // Run the parent `getInitialProps`, it now includes the custom `renderPage`
+ const initialProps = await Document.getInitialProps(ctx)
+
+ return initialProps
+ }
+
+ render() {
+ return (
+ <Html>
+ <Head />
+ <body>
+ <Main />
+ <NextScript />
+ </body>
+ </Html>
+ )
+ }
+}
+
+export default MyDocument
+```
+
+> **Note**: `getInitialProps` in `_document` is not called during client-side transitions.
+
+## TypeScript
+
+You can use the built-in `DocumentContext` type and change the file name to `./pages/_document.tsx` like so:
+
+```tsx
+import Document, { DocumentContext, DocumentInitialProps } from 'next/document'
+
+class MyDocument extends Document {
+ static async getInitialProps(
+ ctx: DocumentContext
+ ): Promise<DocumentInitialProps> {
+ const initialProps = await Document.getInitialProps(ctx)
+
+ return initialProps
+ }
+}
+
+export default MyDocument
+```
diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md
new file mode 100644
index 0000000000000..cd5977c46724e
--- /dev/null
+++ b/docs/advanced-features/custom-error-page.md
@@ -0,0 +1,101 @@
+---
+description: Override and extend the built-in Error page to handle custom errors.
+---
+
+# Custom Error Page
+
+## 404 Page
+
+A 404 page may be accessed very often. Server-rendering an error page for every visit increases the load of the Next.js server. This can result in increased costs and slow experiences.
+
+To avoid the above pitfalls, Next.js provides a static 404 page by default without having to add any additional files.
+
+### Customizing The 404 Page
+
+To create a custom 404 page you can create a `pages/404.js` file. This file is statically generated at build time.
+
+```jsx
+// pages/404.js
+export default function Custom404() {
+ return <h1>404 - Page Not Found</h1>
+}
+```
+
+> **Note**: You can use [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) inside this page if you need to fetch data at build time.
+
+## 500 Page
+
+Server-rendering an error page for every visit adds complexity to responding to errors. To help users get responses to errors as fast as possible, Next.js provides a static 500 page by default without having to add any additional files.
+
+### Customizing The 500 Page
+
+To customize the 500 page you can create a `pages/500.js` file. This file is statically generated at build time.
+
+```jsx
+// pages/500.js
+export default function Custom500() {
+ return <h1>500 - Server-side error occurred</h1>
+}
+```
+
+> **Note**: You can use [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) inside this page if you need to fetch data at build time.
+
+### More Advanced Error Page Customizing
+
+500 errors are handled both client-side and server-side by the `Error` component. If you wish to override it, define the file `pages/_error.js` and add the following code:
+
+```jsx
+function Error({ statusCode }) {
+ return (
+ <p>
+ {statusCode
+ ? `An error ${statusCode} occurred on server`
+ : 'An error occurred on client'}
+ </p>
+ )
+}
+
+Error.getInitialProps = ({ res, err }) => {
+ const statusCode = res ? res.statusCode : err ? err.statusCode : 404
+ return { statusCode }
+}
+
+export default Error
+```
+
+> `pages/_error.js` is only used in production. In development you’ll get an error with the call stack to know where the error originated from.
+
+### Reusing the built-in error page
+
+If you want to render the built-in error page you can by importing the `Error` component:
+
+```jsx
+import Error from 'next/error'
+
+export async function getServerSideProps() {
+ const res = await fetch('https://api.github.com/repos/vercel/next.js')
+ const errorCode = res.ok ? false : res.status
+ const json = await res.json()
+
+ return {
+ props: { errorCode, stars: json.stargazers_count },
+ }
+}
+
+export default function Page({ errorCode, stars }) {
+ if (errorCode) {
+ return <Error statusCode={errorCode} />
+ }
+
+ return <div>Next stars: {stars}</div>
+}
+```
+
+The `Error` component also takes `title` as a property if you want to pass in a text message along with a `statusCode`.
+
+If you have a custom `Error` component be sure to import that one instead. `next/error` exports the default component used by Next.js.
+
+### Caveats
+
+- `Error` does not currently support Next.js [Data Fetching methods](/docs/basic-features/data-fetching.md) like [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) or [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md).
+- `_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/routing/introduction) or rendering in a [custom server](/docs/advanced-features/custom-server).
diff --git a/docs/advanced-features/custom-server.md b/docs/advanced-features/custom-server.md
new file mode 100644
index 0000000000000..89ce91bfb235e
--- /dev/null
+++ b/docs/advanced-features/custom-server.md
@@ -0,0 +1,107 @@
+---
+description: Start a Next.js app programmatically using a custom server.
+---
+
+# Custom Server
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/custom-server">Custom Server</a></li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/ssr-caching">SSR Caching</a></li>
+ </ul>
+</details>
+
+By default, Next.js includes its own server with `next start`. If you have an existing backend, you can still use it with Next.js (this is not a custom server). A custom Next.js server allows you to start a server 100% programmatically in order to use custom server patterns. Most of the time, you will not need this – but it's available for complete customization.
+
+> **Note:** A custom server **cannot** be deployed on [Vercel](https://vercel.com/solutions/nextjs).
+
+> Before deciding to use a custom server, please 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 **serverless functions** and **[Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).**
+
+Take a look at the following example of a custom server:
+
+```js
+// server.js
+const { createServer } = require('http')
+const { parse } = require('url')
+const next = require('next')
+
+const dev = process.env.NODE_ENV !== 'production'
+const hostname = 'localhost'
+const port = 3000
+// when using middleware `hostname` and `port` must be provided below
+const app = next({ dev, hostname, port })
+const handle = app.getRequestHandler()
+
+app.prepare().then(() => {
+ createServer(async (req, res) => {
+ try {
+ // Be sure to pass `true` as the second argument to `url.parse`.
+ // This tells it to parse the query portion of the URL.
+ const parsedUrl = parse(req.url, true)
+ const { pathname, query } = parsedUrl
+
+ if (pathname === '/a') {
+ await app.render(req, res, '/a', query)
+ } else if (pathname === '/b') {
+ await app.render(req, res, '/b', query)
+ } else {
+ await handle(req, res, parsedUrl)
+ }
+ } catch (err) {
+ console.error('Error occurred handling', req.url, err)
+ res.statusCode = 500
+ res.end('internal server error')
+ }
+ }).listen(port, (err) => {
+ if (err) throw err
+ console.log(`> Ready on http://${hostname}:${port}`)
+ })
+})
+```
+
+> `server.js` doesn't go through babel or webpack. Make sure the syntax and sources this file requires are compatible with the current node version you are running.
+
+To run the custom server you'll need to update the `scripts` in `package.json` like so:
+
+```json
+"scripts": {
+ "dev": "node server.js",
+ "build": "next build",
+ "start": "NODE_ENV=production node server.js"
+}
+```
+
+---
+
+The custom server uses the following import to connect the server with the Next.js application:
+
+```js
+const next = require('next')
+const app = next({})
+```
+
+The above `next` import is a function that receives an object with the following options:
+
+- `dev`: `Boolean` - Whether or not to launch Next.js in dev mode. Defaults to `false`
+- `dir`: `String` - Location of the Next.js project. Defaults to `'.'`
+- `quiet`: `Boolean` - Hide error messages containing server information. Defaults to `false`
+- `conf`: `object` - The same object you would use in [next.config.js](/docs/api-reference/next.config.js/introduction.md). Defaults to `{}`
+
+The returned `app` can then be used to let Next.js handle requests as required.
+
+## Disabling file-system routing
+
+By default, `Next` will serve each file in the `pages` folder under a pathname matching the filename. If your project uses a custom server, this behavior may result in the same content being served from multiple paths, which can present problems with SEO and UX.
+
+To disable this behavior and prevent routing based on files in `pages`, open `next.config.js` and disable the `useFileSystemPublicRoutes` config:
+
+```js
+module.exports = {
+ useFileSystemPublicRoutes: false,
+}
+```
+
+> Note that `useFileSystemPublicRoutes` disables filename routes from SSR; client-side routing may still access those paths. When using this option, you should guard against navigation to routes you do not want programmatically.
+
+> You may also wish to configure the client-side router to disallow client-side redirects to filename routes; for that refer to [`router.beforePopState`](/docs/api-reference/next/router.md#router.beforePopState).
diff --git a/docs/advanced-features/customizing-babel-config.md b/docs/advanced-features/customizing-babel-config.md
new file mode 100644
index 0000000000000..aee52289f1589
--- /dev/null
+++ b/docs/advanced-features/customizing-babel-config.md
@@ -0,0 +1,61 @@
+---
+description: Extend the babel preset added by Next.js with your own configs.
+---
+
+# Customizing Babel Config
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-custom-babel-config">Customizing babel configuration</a></li>
+ </ul>
+</details>
+
+Next.js includes the `next/babel` preset to your app, which includes everything needed to compile React applications and server-side code. But if you want to extend the default Babel configs, it's also possible.
+
+To start, you only need to define a `.babelrc` file (or `babel.config.js`) at the top of your app. If such a file is found, it will be considered as the _source of truth_, and therefore it needs to define what Next.js needs as well, which is the `next/babel` preset.
+
+Here's an example `.babelrc` file:
+
+```json
+{
+ "presets": ["next/babel"],
+ "plugins": []
+}
+```
+
+You can [take a look at this file](https://github.com/vercel/next.js/blob/canary/packages/next/build/babel/preset.ts) to learn about the presets included by `next/babel`.
+
+To add presets/plugins **without configuring them**, you can do it this way:
+
+```json
+{
+ "presets": ["next/babel"],
+ "plugins": ["@babel/plugin-proposal-do-expressions"]
+}
+```
+
+To add presets/plugins **with custom configuration**, do it on the `next/babel` preset like so:
+
+```json
+{
+ "presets": [
+ [
+ "next/babel",
+ {
+ "preset-env": {},
+ "transform-runtime": {},
+ "styled-jsx": {},
+ "class-properties": {}
+ }
+ ]
+ ],
+ "plugins": []
+}
+```
+
+To learn more about the available options for each config, visit their documentation site.
+
+> Next.js uses the **current** Node.js version for server-side compilations.
+
+> The `modules` option on `"preset-env"` should be kept to `false`, otherwise webpack code splitting is turned off.
diff --git a/docs/advanced-features/customizing-postcss-config.md b/docs/advanced-features/customizing-postcss-config.md
new file mode 100644
index 0000000000000..a51dd45ce2d01
--- /dev/null
+++ b/docs/advanced-features/customizing-postcss-config.md
@@ -0,0 +1,171 @@
+---
+description: Extend the PostCSS config and plugins added by Next.js with your own.
+---
+
+# Customizing PostCSS Config
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-tailwindcss">Tailwind CSS Example</a></li>
+ </ul>
+</details>
+
+## Default Behavior
+
+Next.js compiles CSS for its [built-in CSS support](/docs/basic-features/built-in-css-support.md) using PostCSS.
+
+Out of the box, with no configuration, Next.js compiles CSS with the following transformations:
+
+1. [Autoprefixer](https://github.com/postcss/autoprefixer) automatically adds vendor prefixes to CSS rules (back to IE11).
+1. [Cross-browser Flexbox bugs](https://github.com/philipwalton/flexbugs) are corrected to behave like [the spec](https://www.w3.org/TR/css-flexbox-1/).
+1. New CSS features are automatically compiled for Internet Explorer 11 compatibility:
+ - [`all` Property](https://developer.mozilla.org/en-US/docs/Web/CSS/all)
+ - [Break Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/break-after)
+ - [`font-variant` Property](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant)
+ - [Gap Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/gap)
+ - [Media Query Ranges](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#Syntax_improvements_in_Level_4)
+
+By default, [CSS Grid](https://www.w3.org/TR/css-grid-1/) and [Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/var) (CSS variables) are **not compiled** for IE11 support.
+
+To compile [CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid) for IE11, you can place the following comment at the top of your CSS file:
+
+```css
+/* autoprefixer grid: autoplace */
+```
+
+You can also enable IE11 support for [CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid)
+in your entire project by configuring autoprefixer with the configuration shown below (collapsed).
+See ["Customizing Plugins"](#customizing-plugins) below for more information.
+
+<details>
+<summary><strong>Click to view the configuration to enable CSS Grid Layout</strong></summary>
+
+```json
+{
+ "plugins": [
+ "postcss-flexbugs-fixes",
+ [
+ "postcss-preset-env",
+ {
+ "autoprefixer": {
+ "flexbox": "no-2009",
+ "grid": "autoplace"
+ },
+ "stage": 3,
+ "features": {
+ "custom-properties": false
+ }
+ }
+ ]
+ ]
+}
+```
+
+</details>
+<br/>
+
+CSS variables are not compiled because it is [not possible to safely do so](https://github.com/MadLittleMods/postcss-css-variables#caveats).
+If you must use variables, consider using something like [Sass variables](https://sass-lang.com/documentation/variables) which are compiled away by [Sass](https://sass-lang.com/).
+
+## Customizing Target Browsers
+
+Next.js allows you to configure the target browsers (for [Autoprefixer](https://github.com/postcss/autoprefixer) and compiled css features) through [Browserslist](https://github.com/browserslist/browserslist).
+
+To customize browserslist, create a `browserslist` key in your `package.json` like so:
+
+```json
+{
+ "browserslist": [">0.3%", "not ie 11", "not dead", "not op_mini all"]
+}
+```
+
+You can use the [browsersl.ist](https://browsersl.ist/?q=%3E0.3%25%2C+not+ie+11%2C+not+dead%2C+not+op_mini+all) tool to visualize what browsers you are targeting.
+
+## CSS Modules
+
+No configuration is needed to support CSS Modules. To enable CSS Modules for a file, rename the file to have the extension `.module.css`.
+
+You can learn more about [Next.js' CSS Module support here](/docs/basic-features/built-in-css-support.md).
+
+## Customizing Plugins
+
+> **Warning**: When you define a custom PostCSS configuration file, Next.js **completely disables** the [default behavior](#default-behavior).
+> Be sure to manually configure all the features you need compiled, including [Autoprefixer](https://github.com/postcss/autoprefixer).
+> You also need to install any plugins included in your custom configuration manually, i.e. `npm install postcss-flexbugs-fixes postcss-preset-env`.
+
+To customize the PostCSS configuration, create a `postcss.config.json` file in the root of your project.
+
+This is the default configuration used by Next.js:
+
+```json
+{
+ "plugins": [
+ "postcss-flexbugs-fixes",
+ [
+ "postcss-preset-env",
+ {
+ "autoprefixer": {
+ "flexbox": "no-2009"
+ },
+ "stage": 3,
+ "features": {
+ "custom-properties": false
+ }
+ }
+ ]
+ ]
+}
+```
+
+> **Note**: Next.js also allows the file to be named `.postcssrc.json`, or, to be read from the `postcss` key in `package.json`.
+
+It is also possible to configure PostCSS with a `postcss.config.js` file, which is useful when you want to conditionally include plugins based on environment:
+
+```js
+module.exports = {
+ plugins:
+ process.env.NODE_ENV === 'production'
+ ? [
+ 'postcss-flexbugs-fixes',
+ [
+ 'postcss-preset-env',
+ {
+ autoprefixer: {
+ flexbox: 'no-2009',
+ },
+ stage: 3,
+ features: {
+ 'custom-properties': false,
+ },
+ },
+ ],
+ ]
+ : [
+ // No transformations in development
+ ],
+}
+```
+
+> **Note**: Next.js also allows the file to be named `.postcssrc.js`.
+
+Do **not use `require()`** to import the PostCSS Plugins. Plugins must be provided as strings.
+
+> **Note**: If your `postcss.config.js` needs to support other non-Next.js tools in the same project, you must use the interoperable object-based format instead:
+>
+> ```js
+> module.exports = {
+> plugins: {
+> 'postcss-flexbugs-fixes': {},
+> 'postcss-preset-env': {
+> autoprefixer: {
+> flexbox: 'no-2009',
+> },
+> stage: 3,
+> features: {
+> 'custom-properties': false,
+> },
+> },
+> },
+> }
+> ```
diff --git a/docs/advanced-features/debugging.md b/docs/advanced-features/debugging.md
new file mode 100644
index 0000000000000..bdcb0a36be2b5
--- /dev/null
+++ b/docs/advanced-features/debugging.md
@@ -0,0 +1,106 @@
+---
+description: Debug your Next.js app.
+---
+
+# Debugging
+
+This documentation explains how you can debug your Next.js frontend and backend code with full source maps support using either the [VS Code debugger](https://code.visualstudio.com/docs/editor/debugging) or [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools).
+
+Any debugger that can attach to Node.js can also be used to debug a Next.js application. You can find more details in the Node.js [Debugging Guide](https://nodejs.org/en/docs/guides/debugging-getting-started/).
+
+## Debugging with VS Code
+
+Create a file named `.vscode/launch.json` at the root of your project with the following content:
+
+```json
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "Next.js: debug server-side",
+ "type": "node-terminal",
+ "request": "launch",
+ "command": "npm run dev"
+ },
+ {
+ "name": "Next.js: debug client-side",
+ "type": "pwa-chrome",
+ "request": "launch",
+ "url": "http://localhost:3000"
+ },
+ {
+ "name": "Next.js: debug full stack",
+ "type": "node-terminal",
+ "request": "launch",
+ "command": "npm run dev",
+ "console": "integratedTerminal",
+ "serverReadyAction": {
+ "pattern": "started server on .+, url: (https?://.+)",
+ "uriFormat": "%s",
+ "action": "debugWithChrome"
+ }
+ }
+ ]
+}
+```
+
+`npm run dev` can be replaced with `yarn dev` if you're using Yarn. If you're [changing the port number](/docs/api-reference/cli#development) your application starts on, replace the `3000` in `http://localhost:3000` with the port you're using instead.
+
+Now go to the Debug panel (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> on Windows/Linux, <kbd>⇧</kbd>+<kbd>⌘</kbd>+<kbd>D</kbd> on macOS), select a launch configuration, then press <kbd>F5</kbd> or select **Debug: Start Debugging** from the Command Palette to start your debugging session.
+
+## Using the Debugger in Jetbrains WebStorm
+
+Click the drop down menu listing the runtime configuration, and click `Edit Configurations...`. Create a `Javascript Debug` debug configuration with `http://localhost:3000` as the URL. Customize to your liking (e.g. Browser for debugging, store as project file), and click `OK`. Run this debug configuration, and the selected browser should automatically open. At this point, you should have 2 applications in debug mode: the NextJS node application, and the client/ browser application.
+
+## Debugging with Chrome DevTools
+
+### Client-side code
+
+Start your development server as usual by running `next dev`, `npm run dev`, or `yarn dev`. Once the server starts, open `http://localhost:3000` (or your alternate URL) in Chrome. Next, open Chrome's Developer Tools (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>J</kbd> on Windows/Linux, <kbd>⌥</kbd>+<kbd>⌘</kbd>+<kbd>I</kbd> on macOS), then go to the **Sources** tab.
+
+Now, any time your client-side code reaches a [`debugger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) statement, code execution will pause and that file will appear in the debug area. You can also press <kbd>Ctrl</kbd>+<kbd>P</kbd> on Windows/Linux or <kbd>⌘</kbd>+<kbd>P</kbd> on macOS to search for a file and set breakpoints manually. Note that when searching here, your source files will have paths starting with `webpack://_N_E/./`.
+
+### Server-side code
+
+To debug server-side Next.js code with Chrome DevTools, you need to pass the [`--inspect`](https://nodejs.org/api/cli.html#cli_inspect_host_port) flag to the underlying Node.js process:
+
+```bash
+NODE_OPTIONS='--inspect' next dev
+```
+
+If you're using `npm run dev` or `yarn dev` (see [Getting Started](/docs/getting-started)) then you should update the `dev` script on your `package.json`:
+
+```json
+"dev": "NODE_OPTIONS='--inspect' next dev"
+```
+
+Launching the Next.js dev server with the `--inspect` flag will look something like this:
+
+```bash
+Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
+For help, see: https://nodejs.org/en/docs/inspector
+ready - started server on 0.0.0.0:3000, url: http://localhost:3000
+```
+
+> Be aware that running `NODE_OPTIONS='--inspect' npm run dev` or `NODE_OPTIONS='--inspect' yarn dev` won't work. This would try to start multiple debuggers on the same port: one for the npm/yarn process and one for Next.js. You would then get an error like `Starting inspector on 127.0.0.1:9229 failed: address already in use` in your console.
+
+Once the server starts, open a new tab in Chrome and visit `chrome://inspect`, where you should see your Next.js application inside the **Remote Target** section. Click **inspect** under your application to open a separate DevTools window, then go to the **Sources** tab.
+
+Debugging server-side code here works much like debugging client-side code with Chrome DevTools, except that when you search for files here with <kbd>Ctrl</kbd>+<kbd>P</kbd> or <kbd>⌘</kbd>+<kbd>P</kbd>, your source files will have paths starting with `webpack://{application-name}/./` (where `{application-name}` will be replaced with the name of your application according to your `package.json` file).
+
+### Debugging on Windows
+
+Windows users may run into an issue when using `NODE_OPTIONS='--inspect'` as that syntax is not supported on Windows platforms. To get around this, install the [`cross-env`](https://www.npmjs.com/package/cross-env) package as a development dependency (`-D` with `npm` and `yarn`) and replace the `dev` script with the following.
+
+```json
+"dev": "cross-env NODE_OPTIONS='--inspect' next dev",
+```
+
+`cross-env` will set the `NODE_OPTIONS` environment variable regardless of which platform you are on (including Mac, Linux, and Windows) and allow you to debug consistently across devices and operating systems.
+
+## More information
+
+To learn more about how to use a JavaScript debugger, take a look at the following documentation:
+
+- [Node.js debugging in VS Code: Breakpoints](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_breakpoints)
+- [Chrome DevTools: Debug JavaScript](https://developers.google.com/web/tools/chrome-devtools/javascript)
diff --git a/docs/advanced-features/dynamic-import.md b/docs/advanced-features/dynamic-import.md
new file mode 100644
index 0000000000000..1122ab5457d84
--- /dev/null
+++ b/docs/advanced-features/dynamic-import.md
@@ -0,0 +1,101 @@
+---
+description: Dynamically import JavaScript modules and React Components and split your code into manageable chunks.
+---
+
+# Dynamic Import
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-dynamic-import">Dynamic Import</a></li>
+ </ul>
+</details>
+
+Next.js supports lazy loading external libraries with `import()` and React components with `next/dynamic`. Deferred loading helps improve the initial loading performance by decreasing the amount of JavaScript necessary to render the page. Components or libraries are only imported and included in the JavaScript bundle when they're used.
+
+`next/dynamic` is an extension of [`React.lazy`](https://reactjs.org/docs/code-splitting.html#reactlazy). When used in combination with [`Suspense`](https://reactjs.org/docs/react-api.html#reactsuspense), components can delay hydration until the Suspense boundary is resolved.
+
+## Example
+
+By using `next/dynamic`, the header component will not be included in the page's initial JavaScript bundle. The page will render the Suspense `fallback` first, followed by the `Header` component when the `Suspense` boundary is resolved.
+
+```jsx
+import dynamic from 'next/dynamic'
+import { Suspense } from 'react'
+
+const DynamicHeader = dynamic(() => import('../components/header'), {
+ suspense: true,
+})
+
+export default function Home() {
+ return (
+ <Suspense fallback={`Loading...`}>
+ <DynamicHeader />
+ </Suspense>
+ )
+}
+```
+
+> **Note**: In `import('path/to/component')`, the path must be explicitly written. It can't be a template string nor a variable. Furthermore the `import()` has to be inside the `dynamic()` call for Next.js to be able to match webpack bundles / module ids to the specific `dynamic()` call and preload them before rendering. `dynamic()` can't be used inside of React rendering as it needs to be marked in the top level of the module for preloading to work, similar to `React.lazy`.
+
+## With named exports
+
+To dynamically import a named export, you can return it from the [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) returned by [`import()`](https://github.com/tc39/proposal-dynamic-import#example):
+
+```jsx
+// components/hello.js
+export function Hello() {
+ return <p>Hello!</p>
+}
+
+// pages/index.js
+import dynamic from 'next/dynamic'
+
+const DynamicComponent = dynamic(() =>
+ import('../components/hello').then((mod) => mod.Hello)
+)
+```
+
+## With no SSR
+
+To dynamically load a component on the client side, you can use the `ssr` option to disable server-rendering. This is useful if an external dependency or component relies on browser APIs like `window`.
+
+```jsx
+import dynamic from 'next/dynamic'
+
+const DynamicHeader = dynamic(() => import('../components/header'), {
+ ssr: false,
+})
+```
+
+## With external libraries
+
+This example uses the external library `fuse.js` for fuzzy search. The module is only loaded in the browser after the user types in the search input.
+
+```jsx
+import { useState } from 'react'
+
+const names = ['Tim', 'Joe', 'Bel', 'Lee']
+
+export default function Page() {
+ const [results, setResults] = useState()
+
+ return (
+ <div>
+ <input
+ type="text"
+ placeholder="Search"
+ onChange={async (e) => {
+ const { value } = e.currentTarget
+ // Dynamically load fuse.js
+ const Fuse = (await import('fuse.js')).default
+ const fuse = new Fuse(names)
+
+ setResults(fuse.search(value))
+ }}
+ />
+ <pre>Results: {JSON.stringify(results, null, 2)}</pre>
+ </div>
+ )
+}
+```
diff --git a/docs/advanced-features/error-handling.md b/docs/advanced-features/error-handling.md
new file mode 100644
index 0000000000000..f4b8d258e5f07
--- /dev/null
+++ b/docs/advanced-features/error-handling.md
@@ -0,0 +1,104 @@
+---
+description: Handle errors in your Next.js app.
+---
+
+# Error Handling
+
+This documentation explains how you can handle development, server-side, and client-side errors.
+
+## Handling Errors in Development
+
+When there is a runtime error during the development phase of your Next.js application, you will encounter an **overlay**. It is a modal that covers the webpage. It is only visible when the development server runs using `next dev`, `npm run dev`, or `yarn dev` and not in production. Fixing the error will automatically dismiss the overlay.
+
+Here is an example of an overlay:
+
+
+
+## Handling Server Errors
+
+Next.js provides a static 500 page by default to handle server-side errors that occur in your application. You can also [customize this page](/docs/advanced-features/custom-error-page#customizing-the-500-page) by creating a `pages/500.js` file.
+
+Having a 500 page in your application does not show specific errors to the app user.
+
+You can also use [404 page](/docs/advanced-features/custom-error-page#404-page) to handle specific runtime error like `file not found`.
+
+## Handling Client Errors
+
+React [Error Boundaries](https://reactjs.org/docs/error-boundaries.html) is a graceful way to handle a JavaScript error on the client so that the other parts of the application continue working. In addition to preventing the page from crashing, it allows you to provide a custom fallback component and even log error information.
+
+To use Error Boundaries for your Next.js application, you must create a class component `ErrorBoundary` and wrap the `Component` prop in the `pages/_app.js` file. This component will be responsible to:
+
+- Render a fallback UI after an error is thrown
+- Provide a way to reset the Application's state
+- Log error information
+
+You can create an `ErrorBoundary` class component by extending `React.Component`. For example:
+
+```jsx
+class ErrorBoundary extends React.Component {
+ constructor(props) {
+ super(props)
+
+ // Define a state variable to track whether is an error or not
+ this.state = { hasError: false }
+ }
+ static getDerivedStateFromError(error) {
+ // Update state so the next render will show the fallback UI
+
+ return { hasError: true }
+ }
+ componentDidCatch(error, errorInfo) {
+ // You can use your own error logging service here
+ console.log({ error, errorInfo })
+ }
+ render() {
+ // Check if the error is thrown
+ if (this.state.hasError) {
+ // You can render any custom fallback UI
+ return (
+ <div>
+ <h2>Oops, there is an error!</h2>
+ <button
+ type="button"
+ onClick={() => this.setState({ hasError: false })}
+ >
+ Try again?
+ </button>
+ </div>
+ )
+ }
+
+ // Return children components in case of no error
+
+ return this.props.children
+ }
+}
+
+export default ErrorBoundary
+```
+
+The `ErrorBoundary` component keeps track of an `hasError` state. The value of this state variable is a boolean. When the value of `hasError` is `true`, then the `ErrorBoundary` component will render a fallback UI. Otherwise, it will render the children components.
+
+After creating an `ErrorBoundary` component, import it in the `pages/_app.js` file to wrap the `Component` prop in your Next.js application.
+
+```jsx
+// Import the ErrorBoundary component
+import ErrorBoundary from '../components/ErrorBoundary'
+
+function MyApp({ Component, pageProps }) {
+ return (
+ // Wrap the Component prop with ErrorBoundary component
+ <ErrorBoundary>
+ <Component {...pageProps} />
+ </ErrorBoundary>
+ )
+}
+
+export default MyApp
+```
+
+You can learn more about [Error Boundaries](https://reactjs.org/docs/error-boundaries.html) in React's documentation.
+
+### Reporting Errors
+
+To monitor client errors, use a service like [Sentry](https://github.com/vercel/next.js/tree/canary/examples/with-sentry), Bugsnag or Datadog.
diff --git a/docs/advanced-features/i18n-routing.md b/docs/advanced-features/i18n-routing.md
new file mode 100644
index 0000000000000..0e0ddf9cc3094
--- /dev/null
+++ b/docs/advanced-features/i18n-routing.md
@@ -0,0 +1,364 @@
+---
+description: Next.js has built-in support for internationalized routing and language detection. Learn more here.
+---
+
+# Internationalized Routing
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/i18n-routing">i18n routing</a></li>
+ </ul>
+</details>
+
+Next.js has built-in support for internationalized ([i18n](https://en.wikipedia.org/wiki/Internationalization_and_localization#Naming)) routing since `v10.0.0`. You can provide a list of locales, the default locale, and domain-specific locales and Next.js will automatically handle the routing.
+
+The i18n routing support is currently meant to complement existing i18n library solutions like [`react-intl`](https://formatjs.io/docs/getting-started/installation), [`react-i18next`](https://react.i18next.com/), [`lingui`](https://lingui.js.org/), [`rosetta`](https://github.com/lukeed/rosetta), [`next-intl`](https://github.com/amannn/next-intl) and others by streamlining the routes and locale parsing.
+
+## Getting started
+
+To get started, add the `i18n` config to your `next.config.js` file.
+
+Locales are [UTS Locale Identifiers](https://www.unicode.org/reports/tr35/tr35-59/tr35.html#Identifiers), a standardized format for defining locales.
+
+Generally a Locale Identifier is made up of a language, region, and script separated by a dash: `language-region-script`. The region and script are optional. An example:
+
+- `en-US` - English as spoken in the United States
+- `nl-NL` - Dutch as spoken in the Netherlands
+- `nl` - Dutch, no specific region
+
+If user locale is `nl-BE` and it is not listed in your configuration, they will be redirected to `nl` if available, or to the default locale otherwise.
+If you don't plan to support all regions of a country, it is therefore a good practice to include country locales that will act as fallbacks.
+
+```js
+// next.config.js
+module.exports = {
+ i18n: {
+ // These are all the locales you want to support in
+ // your application
+ locales: ['en-US', 'fr', 'nl-NL'],
+ // This is the default locale you want to be used when visiting
+ // a non-locale prefixed path e.g. `/hello`
+ defaultLocale: 'en-US',
+ // This is a list of locale domains and the default locale they
+ // should handle (these are only required when setting up domain routing)
+ // Note: subdomains must be included in the domain value to be matched e.g. "fr.example.com".
+ domains: [
+ {
+ domain: 'example.com',
+ defaultLocale: 'en-US',
+ },
+ {
+ domain: 'example.nl',
+ defaultLocale: 'nl-NL',
+ },
+ {
+ domain: 'example.fr',
+ defaultLocale: 'fr',
+ // an optional http field can also be used to test
+ // locale domains locally with http instead of https
+ http: true,
+ },
+ ],
+ },
+}
+```
+
+## Locale Strategies
+
+There are two locale handling strategies: Sub-path Routing and Domain Routing.
+
+### Sub-path Routing
+
+Sub-path Routing puts the locale in the url path.
+
+```js
+// next.config.js
+module.exports = {
+ i18n: {
+ locales: ['en-US', 'fr', 'nl-NL'],
+ defaultLocale: 'en-US',
+ },
+}
+```
+
+With the above configuration `en-US`, `fr`, and `nl-NL` will be available to be routed to, and `en-US` is the default locale. If you have a `pages/blog.js` the following urls would be available:
+
+- `/blog`
+- `/fr/blog`
+- `/nl-nl/blog`
+
+The default locale does not have a prefix.
+
+### Domain Routing
+
+By using domain routing you can configure locales to be served from different domains:
+
+```js
+// next.config.js
+module.exports = {
+ i18n: {
+ locales: ['en-US', 'fr', 'nl-NL', 'nl-BE'],
+ defaultLocale: 'en-US',
+
+ domains: [
+ {
+ // Note: subdomains must be included in the domain value to be matched
+ // e.g. www.example.com should be used if that is the expected hostname
+ domain: 'example.com',
+ defaultLocale: 'en-US',
+ },
+ {
+ domain: 'example.fr',
+ defaultLocale: 'fr',
+ },
+ {
+ domain: 'example.nl',
+ defaultLocale: 'nl-NL',
+ // specify other locales that should be redirected
+ // to this domain
+ locales: ['nl-BE'],
+ },
+ ],
+ },
+}
+```
+
+For example if you have `pages/blog.js` the following urls will be available:
+
+- `example.com/blog`
+- `www.example.com/blog`
+- `example.fr/blog`
+- `example.nl/blog`
+- `example.nl/nl-BE/blog`
+
+## Automatic Locale Detection
+
+When a user visits the application root (generally `/`), Next.js will try to automatically detect which locale the user prefers based on the [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) header and the current domain.
+
+If a locale other than the default locale is detected, the user will be redirected to either:
+
+- **When using Sub-path Routing:** The locale prefixed path
+- **When using Domain Routing:** The domain with that locale specified as the default
+
+When using Domain Routing, if a user with the `Accept-Language` header `fr;q=0.9` visits `example.com`, they will be redirected to `example.fr` since that domain handles the `fr` locale by default.
+
+When using Sub-path Routing, the user would be redirected to `/fr`.
+
+### Prefixing the Default Locale
+
+With Next.js 12 and [Middleware](/docs/middleware.md), we can add a prefix to the default locale with a [workaround](https://github.com/vercel/next.js/discussions/18419).
+
+For example, here's a `next.config.js` file with support for a few languages. Note the `"default"` locale has been added intentionally.
+
+```js
+// next.config.js
+
+module.exports = {
+ i18n: {
+ locales: ['default', 'en', 'de', 'fr'],
+ defaultLocale: 'default',
+ localeDetection: false,
+ },
+ trailingSlash: true,
+}
+```
+
+Next, we can use [Middleware](/docs/middleware.md) to add custom routing rules:
+
+```js
+// middleware.ts
+
+import { NextRequest, NextResponse } from 'next/server'
+
+const PUBLIC_FILE = /\.(.*)$/
+
+export async function middleware(req: NextRequest) {
+ if (
+ req.nextUrl.pathname.startsWith('/_next') ||
+ req.nextUrl.pathname.includes('/api/') ||
+ PUBLIC_FILE.test(req.nextUrl.pathname)
+ ) {
+ return
+ }
+
+ if (req.nextUrl.locale === 'default') {
+ const locale = req.cookies.get('NEXT_LOCALE') || 'en'
+
+ return NextResponse.redirect(
+ new URL(`/${locale}${req.nextUrl.pathname}${req.nextUrl.search}`, req.url)
+ )
+ }
+}
+```
+
+This [Middleware](/docs/middleware.md) skips adding the default prefix to [API Routes](/docs/api-routes/introduction.md) and [public](/docs/basic-features/static-file-serving.md) files like fonts or images. If a request is made to the default locale, we redirect to our prefix `/en`.
+
+### Disabling Automatic Locale Detection
+
+The automatic locale detection can be disabled with:
+
+```js
+// next.config.js
+module.exports = {
+ i18n: {
+ localeDetection: false,
+ },
+}
+```
+
+When `localeDetection` is set to `false` Next.js will no longer automatically redirect based on the user's preferred locale and will only provide locale information detected from either the locale based domain or locale path as described above.
+
+## Accessing the locale information
+
+You can access the locale information via the Next.js router. For example, using the [`useRouter()`](/docs/api-reference/next/router.md#userouter) hook the following properties are available:
+
+- `locale` contains the currently active locale.
+- `locales` contains all configured locales.
+- `defaultLocale` contains the configured default locale.
+
+When [pre-rendering](/docs/basic-features/pages.md#static-generation-recommended) pages with `getStaticProps` or `getServerSideProps`, the locale information is provided in [the context](/docs/basic-features/data-fetching/get-static-props.md) provided to the function.
+
+When leveraging `getStaticPaths`, the configured locales are provided in the context parameter of the function under `locales` and the configured defaultLocale under `defaultLocale`.
+
+## Transition between locales
+
+You can use `next/link` or `next/router` to transition between locales.
+
+For `next/link`, a `locale` prop can be provided to transition to a different locale from the currently active one. If no `locale` prop is provided, the currently active `locale` is used during client-transitions. For example:
+
+```jsx
+import Link from 'next/link'
+
+export default function IndexPage(props) {
+ return (
+ <Link href="/another" locale="fr">
+ To /fr/another
+ </Link>
+ )
+}
+```
+
+When using the `next/router` methods directly, you can specify the `locale` that should be used via the transition options. For example:
+
+```jsx
+import { useRouter } from 'next/router'
+
+export default function IndexPage(props) {
+ const router = useRouter()
+
+ return (
+ <div
+ onClick={() => {
+ router.push('/another', '/another', { locale: 'fr' })
+ }}
+ >
+ to /fr/another
+ </div>
+ )
+}
+```
+
+Note that to handle switching only the `locale` while preserving all routing information such as [dynamic route](/docs/routing/dynamic-routes.md) query values or hidden href query values, you can provide the `href` parameter as an object:
+
+```jsx
+import { useRouter } from 'next/router'
+const router = useRouter()
+const { pathname, asPath, query } = router
+// change just the locale and maintain all other route information including href's query
+router.push({ pathname, query }, asPath, { locale: nextLocale })
+```
+
+See [here](/docs/api-reference/next/router.md#with-url-object) for more information on the object structure for `router.push`.
+
+If you have a `href` that already includes the locale you can opt-out of automatically handling the locale prefixing:
+
+```jsx
+import Link from 'next/link'
+
+export default function IndexPage(props) {
+ return (
+ <Link href="/fr/another" locale={false}>
+ To /fr/another
+ </Link>
+ )
+}
+```
+
+## Leveraging the NEXT_LOCALE cookie
+
+Next.js supports overriding the accept-language header with a `NEXT_LOCALE=the-locale` cookie. This cookie can be set using a language switcher and then when a user comes back to the site it will leverage the locale specified in the cookie when redirecting from `/` to the correct locale location.
+
+For example, if a user prefers the locale `fr` in their accept-language header but a `NEXT_LOCALE=en` cookie is set the `en` locale when visiting `/` the user will be redirected to the `en` locale location until the cookie is removed or expired.
+
+## Search Engine Optimization
+
+Since Next.js knows what language the user is visiting it will automatically add the `lang` attribute to the `<html>` tag.
+
+Next.js doesn't know about variants of a page so it's up to you to add the `hreflang` meta tags using [`next/head`](/docs/api-reference/next/head.md). You can learn more about `hreflang` in the [Google Webmasters documentation](https://support.google.com/webmasters/answer/189077).
+
+## How does this work with Static Generation?
+
+> Note that Internationalized Routing does not integrate with [`next export`](/docs/advanced-features/static-html-export.md) as `next export` does not leverage the Next.js routing layer. Hybrid Next.js applications that do not use `next export` are fully supported.
+
+### Dynamic Routes and `getStaticProps` Pages
+
+For pages using `getStaticProps` with [Dynamic Routes](/docs/routing/dynamic-routes.md), all locale variants of the page desired to be prerendered need to be returned from [`getStaticPaths`](/docs/basic-features/data-fetching/get-static-paths.md). Along with the `params` object returned for `paths`, you can also return a `locale` field specifying which locale you want to render. For example:
+
+```js
+// pages/blog/[slug].js
+export const getStaticPaths = ({ locales }) => {
+ return {
+ paths: [
+ // if no `locale` is provided only the defaultLocale will be generated
+ { params: { slug: 'post-1' }, locale: 'en-US' },
+ { params: { slug: 'post-1' }, locale: 'fr' },
+ ],
+ fallback: true,
+ }
+}
+```
+
+For [Automatically Statically Optimized](/docs/advanced-features/automatic-static-optimization.md) and non-dynamic `getStaticProps` pages, **a version of the page will be generated for each locale**. This is important to consider because it can increase build times depending on how many locales are configured inside `getStaticProps`.
+
+For example, if you have 50 locales configured with 10 non-dynamic pages using `getStaticProps`, this means `getStaticProps` will be called 500 times. 50 versions of the 10 pages will be generated during each build.
+
+To decrease the build time of dynamic pages with `getStaticProps`, use a [`fallback` mode](/docs/api-reference/data-fetching/get-static-paths#fallback-true). This allows you to return only the most popular paths and locales from `getStaticPaths` for prerendering during the build. Then, Next.js will build the remaining pages at runtime as they are requested.
+
+### Automatically Statically Optimized Pages
+
+For pages that are [automatically statically optimized](/docs/advanced-features/automatic-static-optimization.md), a version of the page will be generated for each locale.
+
+### Non-dynamic getStaticProps Pages
+
+For non-dynamic `getStaticProps` pages, a version is generated for each locale like above. `getStaticProps` is called with each `locale` that is being rendered. If you would like to opt-out of a certain locale from being pre-rendered, you can return `notFound: true` from `getStaticProps` and this variant of the page will not be generated.
+
+```js
+export async function getStaticProps({ locale }) {
+ // Call an external API endpoint to get posts.
+ // You can use any data fetching library
+ const res = await fetch(`https://.../posts?locale=${locale}`)
+ const posts = await res.json()
+
+ if (posts.length === 0) {
+ return {
+ notFound: true,
+ }
+ }
+
+ // By returning { props: posts }, the Blog component
+ // will receive `posts` as a prop at build time
+ return {
+ props: {
+ posts,
+ },
+ }
+}
+```
+
+## Limits for the i18n config
+
+- `locales`: 100 total locales
+- `domains`: 100 total locale domain items
+
+> **Note:** These limits have been added initially to prevent potential [performance issues at build time](#dynamic-routes-and-getStaticProps-pages). You can workaround these limits with custom routing using [Middleware](/docs/middleware.md) in Next.js 12.
diff --git a/docs/advanced-features/measuring-performance.md b/docs/advanced-features/measuring-performance.md
new file mode 100644
index 0000000000000..3e7f6d0f56ae0
--- /dev/null
+++ b/docs/advanced-features/measuring-performance.md
@@ -0,0 +1,223 @@
+---
+description: Measure and track page performance using Next.js Analytics
+---
+
+# Measuring performance
+
+[Next.js Analytics](https://nextjs.org/analytics) allows you to analyze and measure the performance of
+pages using different metrics.
+
+You can start collecting your [Real Experience Score](https://vercel.com/docs/concepts/analytics/web-vitals?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) with zero-configuration on [Vercel deployments](https://vercel.com/docs/analytics?utm_source=next-site&utm_medium=docs&utm_campaign=next-website). There's also support for Analytics if you're [self-hosting](https://vercel.com/docs/concepts/analytics#self-hosted?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).
+
+The rest of this documentation describes the built-in relayer Next.js Analytics uses.
+
+## Build Your Own
+
+First, you will need to create a [custom App](/docs/advanced-features/custom-app.md) component and define a `reportWebVitals` function:
+
+```js
+// pages/_app.js
+export function reportWebVitals(metric) {
+ console.log(metric)
+}
+
+function MyApp({ Component, pageProps }) {
+ return <Component {...pageProps} />
+}
+
+export default MyApp
+```
+
+This function is fired when the final values for any of the metrics have finished calculating on
+the page. You can use to log any of the results to the console or send to a particular endpoint.
+
+The `metric` object returned to the function consists of a number of properties:
+
+- `id`: Unique identifier for the metric in the context of the current page load
+- `name`: Metric name
+- `startTime`: First recorded timestamp of the performance entry in [milliseconds](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp) (if applicable)
+- `value`: Value, or duration in [milliseconds](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp), of the performance entry
+- `label`: Type of metric (`web-vital` or `custom`)
+
+There are two types of metrics that are tracked:
+
+- Web Vitals
+- Custom metrics
+
+## Web Vitals
+
+[Web Vitals](https://web.dev/vitals/) are a set of useful metrics that aim to capture the user
+experience of a web page. The following web vitals are all included:
+
+- [Time to First Byte](https://developer.mozilla.org/en-US/docs/Glossary/Time_to_first_byte) (TTFB)
+- [First Contentful Paint](https://developer.mozilla.org/en-US/docs/Glossary/First_contentful_paint) (FCP)
+- [Largest Contentful Paint](https://web.dev/lcp/) (LCP)
+- [First Input Delay](https://web.dev/fid/) (FID)
+- [Cumulative Layout Shift](https://web.dev/cls/) (CLS)
+- [Interaction to Next Paint](https://web.dev/inp/) (INP) _(experimental)_
+
+You can handle all the results of these metrics using the `web-vital` label:
+
+```js
+export function reportWebVitals(metric) {
+ if (metric.label === 'web-vital') {
+ console.log(metric) // The metric object ({ id, name, startTime, value, label }) is logged to the console
+ }
+}
+```
+
+There's also the option of handling each of the metrics separately:
+
+```js
+export function reportWebVitals(metric) {
+ switch (metric.name) {
+ case 'FCP':
+ // handle FCP results
+ break
+ case 'LCP':
+ // handle LCP results
+ break
+ case 'CLS':
+ // handle CLS results
+ break
+ case 'FID':
+ // handle FID results
+ break
+ case 'TTFB':
+ // handle TTFB results
+ break
+ case 'INP':
+ // handle INP results (note: INP is still an experimental metric)
+ break
+ default:
+ break
+ }
+}
+```
+
+A third-party library, [web-vitals](https://github.com/GoogleChrome/web-vitals), is used to measure
+these metrics. Browser compatibility depends on the particular metric, so refer to the [Browser
+Support](https://github.com/GoogleChrome/web-vitals#browser-support) section to find out which
+browsers are supported.
+
+## Custom metrics
+
+In addition to the core metrics listed above, there are some additional custom metrics that
+measure the time it takes for the page to hydrate and render:
+
+- `Next.js-hydration`: Length of time it takes for the page to start and finish hydrating (in ms)
+- `Next.js-route-change-to-render`: Length of time it takes for a page to start rendering after a
+ route change (in ms)
+- `Next.js-render`: Length of time it takes for a page to finish render after a route change (in ms)
+
+You can handle all the results of these metrics using the `custom` label:
+
+```js
+export function reportWebVitals(metric) {
+ if (metric.label === 'custom') {
+ console.log(metric) // The metric object ({ id, name, startTime, value, label }) is logged to the console
+ }
+}
+```
+
+There's also the option of handling each of the metrics separately:
+
+```js
+export function reportWebVitals(metric) {
+ switch (metric.name) {
+ case 'Next.js-hydration':
+ // handle hydration results
+ break
+ case 'Next.js-route-change-to-render':
+ // handle route-change to render results
+ break
+ case 'Next.js-render':
+ // handle render results
+ break
+ default:
+ break
+ }
+}
+```
+
+These metrics work in all browsers that support the [User Timing API](https://caniuse.com/#feat=user-timing).
+
+## Sending results to analytics
+
+With the relay function, you can send any of results to an analytics endpoint to measure and track
+real user performance on your site. For example:
+
+```js
+export function reportWebVitals(metric) {
+ const body = JSON.stringify(metric)
+ const url = 'https://example.com/analytics'
+
+ // Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
+ if (navigator.sendBeacon) {
+ navigator.sendBeacon(url, body)
+ } else {
+ fetch(url, { body, method: 'POST', keepalive: true })
+ }
+}
+```
+
+> **Note**: If you use [Google Analytics](https://analytics.google.com/analytics/web/), using the
+> `id` value can allow you to construct metric distributions manually (to calculate percentiles,
+> etc.)
+>
+> ```js
+> export function reportWebVitals({ id, name, label, value }) {
+> // Use `window.gtag` if you initialized Google Analytics as this example:
+> // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics/pages/_app.js
+> window.gtag('event', name, {
+> event_category:
+> label === 'web-vital' ? 'Web Vitals' : 'Next.js custom metric',
+> value: Math.round(name === 'CLS' ? value * 1000 : value), // values must be integers
+> event_label: id, // id unique to current page load
+> non_interaction: true, // avoids affecting bounce rate.
+> })
+> }
+> ```
+>
+> Read more about [sending results to Google Analytics](https://github.com/GoogleChrome/web-vitals#send-the-results-to-google-analytics).
+
+## Web Vitals Attribution
+
+When debugging issues related to Web Vitals, it is often helpful if we can pinpoint the source of the problem.
+For example, in the case of Cumulative Layout Shift (CLS), we might want to know the first element that shifted when the single largest layout shift occurred.
+Or, in the case of Largest Contentful Paint (LCP), we might want to identify the element corresponding to the LCP for the page.
+If the LCP element is an image, knowing the URL of the image resource can help us locate the asset we need to optimize.
+
+Pinpointing the biggest contributor to the Web Vitals score, aka [attribution](https://github.com/GoogleChrome/web-vitals/blob/4ca38ae64b8d1e899028c692f94d4c56acfc996c/README.md#attribution),
+allows us to obtain more in-depth information like entries for [PerformanceEventTiming](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEventTiming), [PerformanceNavigationTiming](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming) and [PerformanceResourceTiming](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).
+
+Attribution is disabled by default in Next.js but can be enabled **per metric** by specifying the following in `next.config.js`.
+
+```js
+// next.config.js
+experimental: {
+ webVitalsAttribution: ['CLS', 'LCP']
+}
+```
+
+Valid attribution values are all `web-vitals` metrics specified in the [`NextWebVitalsMetric`](https://github.com/vercel/next.js/blob/442378d21dd56d6e769863eb8c2cb521a463a2e0/packages/next/shared/lib/utils.ts#L43) type.
+
+## TypeScript
+
+If you are using TypeScript, you can use the built-in type `NextWebVitalsMetric`:
+
+```ts
+// pages/_app.tsx
+
+import type { AppProps, NextWebVitalsMetric } from 'next/app'
+
+function MyApp({ Component, pageProps }: AppProps) {
+ return <Component {...pageProps} />
+}
+
+export function reportWebVitals(metric: NextWebVitalsMetric) {
+ console.log(metric)
+}
+
+export default MyApp
+```
diff --git a/docs/advanced-features/middleware.md b/docs/advanced-features/middleware.md
new file mode 100644
index 0000000000000..5d38627289a9d
--- /dev/null
+++ b/docs/advanced-features/middleware.md
@@ -0,0 +1,281 @@
+---
+description: Learn how to use Middleware to run code before a request is completed.
+---
+
+# Middleware
+
+<details open>
+<summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | ------------------------------------------------------------------------------------------ |
+| `v13.0.0` | Middleware can modify request headers, response headers, and send responses |
+| `v12.2.0` | Middleware is stable |
+| `v12.0.9` | Enforce absolute URLs in Edge Runtime ([PR](https://github.com/vercel/next.js/pull/33410)) |
+| `v12.0.0` | Middleware (Beta) added |
+
+</details>
+
+Middleware allows you to run code before a request is completed, then based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.
+
+Middleware runs _before_ cached content, so you can personalize static files and pages. Common examples of Middleware would be authentication, A/B testing, localized pages, bot protection, and more. Regarding localized pages, you can start with [i18n routing](/docs/advanced-features/i18n-routing) and implement Middleware for more advanced use cases.
+
+> **Note:** If you were using Middleware prior to `12.2`, please see the [upgrade guide](https://nextjs.org/docs/messages/middleware-upgrade-guide).
+
+## Using Middleware
+
+To begin using Middleware, follow the steps below:
+
+1. Install the latest version of Next.js:
+
+```bash
+npm install next@latest
+```
+
+2. Create a `middleware.ts` (or `.js`) file at the root or in the `src` directory (same level as your `pages`)
+3. Export a middleware function from the `middleware.ts` file:
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+// This function can be marked `async` if using `await` inside
+export function middleware(request: NextRequest) {
+ return NextResponse.redirect(new URL('/about-2', request.url))
+}
+
+// See "Matching Paths" below to learn more
+export const config = {
+ matcher: '/about/:path*',
+}
+```
+
+## Matching Paths
+
+Middleware will be invoked for **every route in your project**. The following is the execution order:
+
+1. `headers` from `next.config.js`
+2. `redirects` from `next.config.js`
+3. Middleware (`rewrites`, `redirects`, etc.)
+4. `beforeFiles` (`rewrites`) from `next.config.js`
+5. Filesystem routes (`public/`, `_next/static/`, Pages, etc.)
+6. `afterFiles` (`rewrites`) from `next.config.js`
+7. Dynamic Routes (`/blog/[slug]`)
+8. `fallback` (`rewrites`) from `next.config.js`
+
+There are two ways to define which paths Middleware will run on:
+
+1. Custom matcher config
+2. Conditional statements
+
+### Matcher
+
+`matcher` allows you to filter Middleware to run on specific paths.
+
+```js
+export const config = {
+ matcher: '/about/:path*',
+}
+```
+
+You can match a single path or multiple paths with an array syntax:
+
+```js
+export const config = {
+ matcher: ['/about/:path*', '/dashboard/:path*'],
+}
+```
+
+The `matcher` config allows full regex so matching like negative lookaheads or character matching is supported. An example of a negative lookahead to match all except specific paths can be seen here:
+
+```js
+export const config = {
+ matcher: [
+ /*
+ * Match all request paths except for the ones starting with:
+ * - api (API routes)
+ * - _next/static (static files)
+ * - favicon.ico (favicon file)
+ */
+ '/((?!api|_next/static|favicon.ico).*)',
+ ],
+}
+```
+
+> **Note:** The `matcher` values need to be constants so they can be statically analyzed at build-time. Dynamic values such as variables will be ignored.
+
+Configured matchers:
+
+1. MUST start with `/`
+2. Can include named parameters: `/about/:path` matches `/about/a` and `/about/b` but not `/about/a/c`
+3. Can have modifiers on named parameters (starting with `:`): `/about/:path*` matches `/about/a/b/c` because `*` is _zero or more_. `?` is _zero or one_ and `+` _one or more_
+4. Can use regular expression enclosed in parenthesis: `/about/(.*)` is the same as `/about/:path*`
+
+Read more details on [path-to-regexp](https://github.com/pillarjs/path-to-regexp#path-to-regexp-1) documentation.
+
+> **Note:** For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match.
+
+### Conditional Statements
+
+```typescript
+// middleware.ts
+
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+ if (request.nextUrl.pathname.startsWith('/about')) {
+ return NextResponse.rewrite(new URL('/about-2', request.url))
+ }
+
+ if (request.nextUrl.pathname.startsWith('/dashboard')) {
+ return NextResponse.rewrite(new URL('/dashboard/user', request.url))
+ }
+}
+```
+
+## NextResponse
+
+The [`NextResponse`](#nextresponse) API allows you to:
+
+- `redirect` the incoming request to a different URL
+- `rewrite` the response by displaying a given URL
+- Set request headers for API Routes, `getServerSideProps`, and `rewrite` destinations
+- Set response cookies
+- Set response headers
+
+To produce a response from Middleware, you should `rewrite` to a route ([Page](/docs/basic-features/pages.md) or [Edge API Route](/docs/api-routes/edge-api-routes.md)) that produces a response.
+
+## Using Cookies
+
+Cookies are regular headers. On a `Request`, they are stored in the `Cookie` header. On a `Response` they are in the `Set-Cookie` header. Next.js provides a convenient way to access and manipulate these cookies through the `cookies` extension on `NextRequest` and `NextResponse`.
+
+1. For incoming requests, `cookies` comes with the following methods: `get`, `getAll`, `set`, and `delete` cookies. You can check for the existence of a cookie with `has` or remove all cookies with `clear`.
+2. For outgoing responses, `cookies` have the following methods `get`, `getAll`, `set`, and `delete`.
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+ // Assume a "Cookie:nextjs=fast" header to be present on the incoming request
+ // Getting cookies from the request using the `RequestCookies` API
+ const cookie = request.cookies.get('nextjs')?.value
+ console.log(cookie) // => 'fast'
+ const allCookies = request.cookies.getAll()
+ console.log(allCookies) // => [{ name: 'vercel', value: 'fast' }]
+
+ request.cookies.has('nextjs') // => true
+ request.cookies.delete('nextjs')
+ request.cookies.has('nextjs') // => false
+
+ // Setting cookies on the response using the `ResponseCookies` API
+ const response = NextResponse.next()
+ response.cookies.set('vercel', 'fast')
+ response.cookies.set({
+ name: 'vercel',
+ value: 'fast',
+ path: '/test',
+ })
+ const cookie = response.cookies.get('vercel')
+ console.log(cookie) // => { name: 'vercel', value: 'fast', Path: '/test' }
+ // The outgoing response will have a `Set-Cookie:vercel=fast;path=/test` header.
+
+ return response
+}
+```
+
+## Setting Headers
+
+You can set request and response headers using the `NextResponse` API (setting _request_ headers is available since Next.js v13.0.0).
+
+```ts
+// middleware.ts
+
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+ // Clone the request headers and set a new header `x-hello-from-middleware1`
+ const requestHeaders = new Headers(request.headers)
+ requestHeaders.set('x-hello-from-middleware1', 'hello')
+
+ // You can also set request headers in NextResponse.rewrite
+ const response = NextResponse.next({
+ request: {
+ // New request headers
+ headers: requestHeaders,
+ },
+ })
+
+ // Set a new response header `x-hello-from-middleware2`
+ response.headers.set('x-hello-from-middleware2', 'hello')
+ return response
+}
+```
+
+> **Note:** Avoid setting large headers as it might cause [431 Request Header Fields Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431) error depending on your backend web server configuration.
+
+## Producing a Response
+
+You can respond to middleware directly by returning a `NextResponse` (responding from middleware is available since Next.js v13.0.0).
+
+To enable middleware responses, update `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+ experimental: {
+ allowMiddlewareResponseBody: true,
+ },
+}
+```
+
+Once enabled, you can provide a response from middleware using the `Response` or `NextResponse` API:
+
+```ts
+// middleware.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { isAuthenticated } from '@lib/auth'
+
+// Limit the middleware to paths starting with `/api/`
+export const config = {
+ matcher: '/api/:function*',
+}
+
+export function middleware(request: NextRequest) {
+ // Call our authentication function to check the request
+ if (!isAuthenticated(request)) {
+ // Respond with JSON indicating an error message
+ return new NextResponse(
+ JSON.stringify({ success: false, message: 'authentication failed' }),
+ { status: 401, headers: { 'content-type': 'application/json' } }
+ )
+ }
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/edge-runtime.md">
+ <b>Edge Runtime</b>
+ <small>Learn more about the supported Web APIs available.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-reference/next/server.md">
+ <b>Middleware API Reference</b>
+ <small>Learn more about the supported APIs for Middleware.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-routes/edge-api-routes.md">
+ <b>Edge API Routes</b>
+ <small>Build high performance APIs in Next.js. </small>
+ </a>
+</div>
diff --git a/docs/advanced-features/module-path-aliases.md b/docs/advanced-features/module-path-aliases.md
new file mode 100644
index 0000000000000..ec19e194bbfd3
--- /dev/null
+++ b/docs/advanced-features/module-path-aliases.md
@@ -0,0 +1,95 @@
+---
+description: Configure module path aliases that allow you to remap certain import paths.
+---
+
+# Absolute Imports and Module path aliases
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-absolute-imports">Absolute Imports and Aliases</a></li>
+ </ul>
+</details>
+
+Next.js automatically supports the `tsconfig.json` and `jsconfig.json` `"paths"` and `"baseUrl"` options since [Next.js 9.4](https://nextjs.org/blog/next-9-4).
+
+> Note: `jsconfig.json` can be used when you don't use TypeScript
+
+> Note: you need to restart dev server to reflect modifications done in `tsconfig.json` / `jsconfig.json`
+
+These options allow you to configure module aliases, for example a common pattern is aliasing certain directories to use absolute paths.
+
+One useful feature of these options is that they integrate automatically into certain editors, for example vscode.
+
+The `baseUrl` configuration option allows you to import directly from the root of the project.
+
+An example of this configuration:
+
+```json
+// tsconfig.json or jsconfig.json
+{
+ "compilerOptions": {
+ "baseUrl": "."
+ }
+}
+```
+
+```jsx
+// components/button.js
+export default function Button() {
+ return <button>Click me</button>
+}
+```
+
+```jsx
+// pages/index.js
+import Button from 'components/button'
+
+export default function HomePage() {
+ return (
+ <>
+ <h1>Hello World</h1>
+ <Button />
+ </>
+ )
+}
+```
+
+While `baseUrl` is useful you might want to add other aliases that don't match 1 on 1. For this TypeScript has the `"paths"` option.
+
+Using `"paths"` allows you to configure module aliases. For example `@/components/*` to `components/*`.
+
+An example of this configuration:
+
+```json
+// tsconfig.json or jsconfig.json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "paths": {
+ "@/components/*": ["components/*"]
+ }
+ }
+}
+```
+
+```jsx
+// components/button.js
+export default function Button() {
+ return <button>Click me</button>
+}
+```
+
+```jsx
+// pages/index.js
+import Button from '@/components/button'
+
+export default function HomePage() {
+ return (
+ <>
+ <h1>Hello World</h1>
+ <Button />
+ </>
+ )
+}
+```
diff --git a/docs/advanced-features/multi-zones.md b/docs/advanced-features/multi-zones.md
new file mode 100644
index 0000000000000..2045d487cecf7
--- /dev/null
+++ b/docs/advanced-features/multi-zones.md
@@ -0,0 +1,30 @@
+# Multi Zones
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-zones">With Zones</a></li>
+ </ul>
+</details>
+
+A zone is a single deployment of a Next.js app. You can have multiple zones and merge them as a single app.
+
+For example, let's say you have the following apps:
+
+- An app for serving `/blog/**`
+- Another app for serving all other pages
+
+With multi zones support, you can merge both these apps into a single one allowing your customers to browse it using a single URL, but you can develop and deploy both apps independently.
+
+## How to define a zone
+
+There are no zone related APIs. You only need to do the following:
+
+- Make sure to keep only the pages you need in your app, meaning that an app can't have pages from another app, if app `A` has `/blog` then app `B` shouldn't have it too.
+- Make sure to configure a [basePath](/docs/api-reference/next.config.js/basepath.md) to avoid conflicts with pages and static files.
+
+## How to merge zones
+
+You can merge zones using [`rewrites`](/docs/api-reference/next.config.js/rewrites.md) in one of the apps or any HTTP proxy.
+
+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 both apps with a single `git push`.
diff --git a/docs/advanced-features/output-file-tracing.md b/docs/advanced-features/output-file-tracing.md
new file mode 100644
index 0000000000000..3c035f28e33ee
--- /dev/null
+++ b/docs/advanced-features/output-file-tracing.md
@@ -0,0 +1,110 @@
+---
+description: Next.js automatically traces which files are needed by each page to allow for easy deployment of your application. Learn how it works here.
+---
+
+# Output File Tracing
+
+During a build, Next.js will automatically trace each page and its dependencies to determine all of the files that are needed for deploying a production version of your application.
+
+This feature helps reduce the size of deployments drastically. Previously, when deploying with Docker you would need to have all files from your package's `dependencies` installed to run `next start`. Starting with Next.js 12, you can leverage Output File Tracing in the `.next/` directory to only include the necessary files.
+
+Furthermore, this removes the need for the deprecated `serverless` target which can cause various issues and also creates unnecessary duplication.
+
+## How It Works
+
+During `next build`, Next.js will use [`@vercel/nft`](https://github.com/vercel/nft) to statically analyze `import`, `require`, and `fs` usage to determine all files that a page might load.
+
+Next.js' production server is also traced for its needed files and output at `.next/next-server.js.nft.json` which can be leveraged in production.
+
+To leverage the `.nft.json` files emitted to the `.next` output directory, you can read the list of files in each trace that are relative to the `.nft.json` file and then copy them to your deployment location.
+
+## Automatically Copying Traced Files
+
+Next.js can automatically create a `standalone` folder that copies only the necessary files for a production deployment including select files in `node_modules`.
+
+To leverage this automatic copying you can enable it in your `next.config.js`:
+
+```js
+module.exports = {
+ output: 'standalone',
+}
+```
+
+This will create a folder at `.next/standalone` which can then be deployed on its own without installing `node_modules`.
+
+Additionally, a minimal `server.js` file is also output which can be used instead of `next start`. This minimal server does not copy the `public` or `.next/static` folders by default as these should ideally be handled by a CDN instead, although these folders can be copied to the `standalone/public` and `standalone/.next/static` folders manually, after which `server.js` file will serve these automatically.
+
+Note: `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/api-reference/next.config.js/runtime-configuration.md) are being used, the values will be specific to values at build time.
+
+If your project uses [Image Optimization](/docs/basic-features/image-optimization.md) with the default `loader`, you must install `sharp` as a dependency:
+
+```bash
+npm i sharp
+```
+
+```bash
+yarn add sharp
+```
+
+```bash
+pnpm add sharp
+```
+
+## Caveats
+
+- While tracing in monorepo setups, the project directory is used for tracing by default. For `next build packages/web-app`, `packages/web-app` would be the tracing root and any files outside of that folder will not be included. To include files outside of this folder you can set `experimental.outputFileTracingRoot` in your `next.config.js`.
+
+```js
+// packages/web-app/next.config.js
+module.exports = {
+ experimental: {
+ // this includes files from the monorepo base two directories up
+ outputFileTracingRoot: path.join(__dirname, '../../'),
+ },
+}
+```
+
+- There are some cases in which Next.js might fail to include required files, or might incorrectly include unused files. In those cases, you can export page configs props `unstable_includeFiles` and `unstable_excludeFiles` respectively. Each prop accepts an array of [minimatch globs](https://www.npmjs.com/package/minimatch) relative to the project's root to either include or exclude in the trace.
+- 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`
+
+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.
+
+To enable it, you can add the following configuration to your `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+ experimental: {
+ turbotrace: {
+ // control the log level of the turbotrace, default is `error`
+ logLevel?:
+ | 'bug'
+ | 'fatal'
+ | 'error'
+ | 'warning'
+ | 'hint'
+ | 'note'
+ | 'suggestions'
+ | 'info',
+ // control if the log of turbotrace should contain the details of the analysis, default is `false`
+ logDetail?: boolean
+ // show all log messages without limit
+ // turbotrace only show 1 log message for each categories by default
+ logAll?: boolean
+ // control the context directory of the turbotrace
+ // files outside of the context directory will not be traced
+ // set the `experimental.outputFileTracingRoot` has the same effect
+ // if the `experimental.outputFileTracingRoot` and this option are both set, the `experimental.turbotrace.contextDirectory` will be used
+ contextDirectory?: string
+ // if there is `process.cwd()` expression in your code, you can set this option to tell `turbotrace` the value of `process.cwd()` while tracing.
+ // for example the require(process.cwd() + '/package.json') will be traced as require('/path/to/cwd/package.json')
+ processCwd?: string,
+ // control the maximum number of files that are passed to the `turbotrace`
+ // default is 128
+ maxFiles?: number;
+ },
+ },
+}
+```
diff --git a/docs/advanced-features/preview-mode.md b/docs/advanced-features/preview-mode.md
new file mode 100644
index 0000000000000..7cd5a07a09620
--- /dev/null
+++ b/docs/advanced-features/preview-mode.md
@@ -0,0 +1,259 @@
+---
+description: Next.js has the preview mode for statically generated pages. You can learn how it works here.
+---
+
+# Preview Mode
+
+> This document is for Next.js versions 9.3 and up. If you’re using older versions of Next.js, refer to our [previous documentation](https://nextjs.org/docs/tag/v9.2.2/basic-features/pages).
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-wordpress">WordPress Example</a> (<a href="https://next-blog-wordpress.vercel.app">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-datocms">DatoCMS Example</a> (<a href="https://next-blog-datocms.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-takeshape">TakeShape Example</a> (<a href="https://next-blog-takeshape.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-sanity">Sanity Example</a> (<a href="https://next-blog-sanity.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-prismic">Prismic Example</a> (<a href="https://next-blog-prismic.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-contentful">Contentful Example</a> (<a href="https://next-blog-contentful.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-strapi">Strapi Example</a> (<a href="https://next-blog-strapi.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-prepr">Prepr Example</a> (<a href="https://next-blog-prepr.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-agilitycms">Agility CMS Example</a> (<a href="https://next-blog-agilitycms.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-cosmic">Cosmic Example</a> (<a href="https://next-blog-cosmic.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-buttercms">ButterCMS Example</a> (<a href="https://next-blog-buttercms.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-storyblok">Storyblok Example</a> (<a href="https://next-blog-storyblok.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-graphcms">GraphCMS Example</a> (<a href="https://next-blog-graphcms.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-kontent">Kontent Example</a> (<a href="https://next-blog-kontent.vercel.app//">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-umbraco-heartcore">Umbraco Heartcore Example</a> (<a href="https://next-blog-umbraco-heartcore.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-plasmic">Plasmic Example</a> (<a href="https://nextjs-plasmic-example.vercel.app/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-enterspeed">Enterspeed Example</a> (<a href="https://next-blog-demo.enterspeed.com/">Demo</a>)</li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/cms-makeswift">Makeswift Example</a> (<a href="https://nextjs-makeswift-example.vercel.app/">Demo</a>)</li>
+ </ul>
+</details>
+
+In the [Pages documentation](/docs/basic-features/pages.md) and the [Data Fetching documentation](/docs/basic-features/data-fetching/overview.md), we talked about how to pre-render a page at build time (**Static Generation**) using `getStaticProps` and `getStaticPaths`.
+
+Static Generation is useful when your pages fetch data from a headless CMS. However, it’s not ideal when you’re writing a draft on your headless CMS and want to **preview** the draft immediately on your page. You’d want Next.js to render these pages at **request time** instead of build time and fetch the draft content instead of the published content. You’d want Next.js to bypass Static Generation only for this specific case.
+
+Next.js has a feature called **Preview Mode** which solves this problem. Here are instructions on how to use it.
+
+## Step 1. Create and access a preview API route
+
+> Take a look at the [API Routes documentation](/docs/api-routes/introduction.md) first if you’re not familiar with Next.js API Routes.
+
+First, create a **preview API route**. It can have any name - e.g. `pages/api/preview.js` (or `.ts` if using TypeScript).
+
+In this API route, you need to call `setPreviewData` on the response object. The argument for `setPreviewData` should be an object, and this can be used by `getStaticProps` (more on this later). For now, we’ll use `{}`.
+
+```js
+export default function handler(req, res) {
+ // ...
+ res.setPreviewData({})
+ // ...
+}
+```
+
+`res.setPreviewData` sets some **cookies** on the browser which turns on the preview mode. Any requests to Next.js containing these cookies will be considered as the **preview mode**, and the behavior for statically generated pages will change (more on this later).
+
+You can test this manually by creating an API route like below and accessing it from your browser manually:
+
+```js
+// A simple example for testing it manually from your browser.
+// If this is located at pages/api/preview.js, then
+// open /api/preview from your browser.
+export default function handler(req, res) {
+ res.setPreviewData({})
+ res.end('Preview mode enabled')
+}
+```
+
+If you use your browser’s developer tools, you’ll notice that the `__prerender_bypass` and `__next_preview_data` cookies will be set on this request.
+
+### Securely accessing it from your Headless CMS
+
+In practice, you’d want to call this API route _securely_ from your headless CMS. The specific steps will vary depending on which headless CMS you’re using, but here are some common steps you could take.
+
+These steps assume that the headless CMS you’re using supports setting **custom preview URLs**. If it doesn’t, you can still use this method to secure your preview URLs, but you’ll need to construct and access the preview URL manually.
+
+**First**, you should create a **secret token string** using a token generator of your choice. This secret will only be known by your Next.js app and your headless CMS. This secret prevents people who don’t have access to your CMS from accessing preview URLs.
+
+**Second**, if your headless CMS supports setting custom preview URLs, specify the following as the preview URL. (This assumes that your preview API route is located at `pages/api/preview.js`.)
+
+```bash
+https://<your-site>/api/preview?secret=<token>&slug=<path>
+```
+
+- `<your-site>` should be your deployment domain.
+- `<token>` should be replaced with the secret token you generated.
+- `<path>` should be the path for the page that you want to preview. If you want to preview `/posts/foo`, then you should use `&slug=/posts/foo`.
+
+Your headless CMS might allow you to include a variable in the preview URL so that `<path>` can be set dynamically based on the CMS’s data like so: `&slug=/posts/{entry.fields.slug}`
+
+**Finally**, in the preview API route:
+
+- Check that the secret matches and that the `slug` parameter exists (if not, the request should fail).
+-
+- Call `res.setPreviewData`.
+- Then redirect the browser to the path specified by `slug`. (The following example uses a [307 redirect](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307)).
+
+```js
+export default async (req, res) => {
+ // Check the secret and next parameters
+ // This secret should only be known to this API route and the CMS
+ if (req.query.secret !== 'MY_SECRET_TOKEN' || !req.query.slug) {
+ return res.status(401).json({ message: 'Invalid token' })
+ }
+
+ // Fetch the headless CMS to check if the provided `slug` exists
+ // getPostBySlug would implement the required fetching logic to the headless CMS
+ const post = await getPostBySlug(req.query.slug)
+
+ // If the slug doesn't exist prevent preview mode from being enabled
+ if (!post) {
+ return res.status(401).json({ message: 'Invalid slug' })
+ }
+
+ // Enable Preview Mode by setting the cookies
+ res.setPreviewData({})
+
+ // Redirect to the path from the fetched post
+ // We don't redirect to req.query.slug as that might lead to open redirect vulnerabilities
+ res.redirect(post.slug)
+}
+```
+
+If it succeeds, then the browser will be redirected to the path you want to preview with the preview mode cookies being set.
+
+## Step 2. Update `getStaticProps`
+
+The next step is to update `getStaticProps` to support the preview mode.
+
+If you request a page which has `getStaticProps` with the preview mode cookies set (via `res.setPreviewData`), then `getStaticProps` will be called at **request time** (instead of at build time).
+
+Furthermore, it will be called with a `context` object where:
+
+- `context.preview` will be `true`.
+- `context.previewData` will be the same as the argument used for `setPreviewData`.
+
+```js
+export async function getStaticProps(context) {
+ // If you request this page with the preview mode cookies set:
+ //
+ // - context.preview will be true
+ // - context.previewData will be the same as
+ // the argument used for `setPreviewData`.
+}
+```
+
+We used `res.setPreviewData({})` in the preview API route, so `context.previewData` will be `{}`. You can use this to pass session information from the preview API route to `getStaticProps` if necessary.
+
+If you’re also using `getStaticPaths`, then `context.params` will also be available.
+
+### Fetch preview data
+
+You can update `getStaticProps` to fetch different data based on `context.preview` and/or `context.previewData`.
+
+For example, your headless CMS might have a different API endpoint for draft posts. If so, you can use `context.preview` to modify the API endpoint URL like below:
+
+```js
+export async function getStaticProps(context) {
+ // If context.preview is true, append "/preview" to the API endpoint
+ // to request draft data instead of published data. This will vary
+ // based on which headless CMS you're using.
+ const res = await fetch(`https://.../${context.preview ? 'preview' : ''}`)
+ // ...
+}
+```
+
+That’s it! If you access the preview API route (with `secret` and `slug`) from your headless CMS or manually, you should now be able to see the preview content. And if you update your draft without publishing, you should be able to preview the draft.
+
+```bash
+# Set this as the preview URL on your headless CMS or access manually,
+# and you should be able to see the preview.
+https://<your-site>/api/preview?secret=<token>&slug=<path>
+```
+
+## More Details
+
+> **Note**: during rendering `next/router` exposes an `isPreview` flag, see the [router object docs](/docs/api-reference/next/router.md#router-object) for more info.
+
+### Clear the Preview Mode cookies
+
+By default, no expiration date is set for Preview Mode cookies, so the preview session ends when the browser is closed.
+
+To clear the Preview Mode cookies manually, create an API route that calls `clearPreviewData()`:
+
+```js
+// pages/api/clear-preview-mode-cookies.js
+
+export default function handler(req, res) {
+ res.clearPreviewData()
+}
+```
+
+Then, send a request to `/api/clear-preview-mode-cookies` to invoke the API Route. If calling this route using [`next/link`](/docs/api-reference/next/link.md), you must pass `prefetch={false}` to prevent calling `clearPreviewData` during link prefetching.
+
+### Specify the Preview Mode duration
+
+`setPreviewData` takes an optional second parameter which should be an options object. It accepts the following keys:
+
+- `maxAge`: Specifies the number (in seconds) for the preview session to last for.
+- `path`: Specifies the path the cookie should be applied under. Defaults to `/` enabling preview mode for all paths.
+
+```js
+setPreviewData(data, {
+ maxAge: 60 * 60, // The preview mode cookies expire in 1 hour
+ path: '/about', // The preview mode cookies apply to paths with /about
+})
+```
+
+### `previewData` size limits
+
+You can pass an object to `setPreviewData` and have it be available in `getStaticProps`. However, because the data will be stored in a cookie, there’s a size limitation. Currently, preview data is limited to 2KB.
+
+### Works with `getServerSideProps`
+
+The preview mode works on `getServerSideProps` as well. It will also be available on the `context` object containing `preview` and `previewData`.
+
+### Works with API Routes
+
+API Routes will have access to `preview` and `previewData` under the request object. For example:
+
+```js
+export default function myApiRoute(req, res) {
+ const isPreview = req.preview
+ const previewData = req.previewData
+ // ...
+}
+```
+
+### Unique per `next build`
+
+Both the bypass cookie value and the private key for encrypting the `previewData` change when `next build` is completed.
+This ensures that the bypass cookie can’t be guessed.
+
+> **Note:** To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access.
+
+## Learn more
+
+The following pages might also be useful.
+
+<div class="card">
+ <a href="/docs/basic-features/data-fetching/overview.md">
+ <b>Data Fetching:</b>
+ <small>Learn more about data fetching in Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-routes/introduction.md">
+ <b>API Routes:</b>
+ <small>Learn more about API routes in Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/environment-variables.md">
+ <b>Environment Variables:</b>
+ <small>Learn more about environment variables in Next.js.</small>
+ </a>
+</div>
diff --git a/docs/advanced-features/react-18/overview.md b/docs/advanced-features/react-18/overview.md
new file mode 100644
index 0000000000000..7c9f7d8403eb7
--- /dev/null
+++ b/docs/advanced-features/react-18/overview.md
@@ -0,0 +1,34 @@
+# React 18
+
+Next.js 13 requires using React 18, unlocking:
+
+- [Streaming SSR](#streaming-ssr)
+- [React Server Components](#react-server-components)
+- [Edge and Node.js Runtimes](#edge-and-nodejs-runtimes)
+- New APIs like `startTransition` and more.
+
+## Streaming SSR
+
+In Next.js 13, you can start using the `app/` directory (beta) to take advantage of streaming server-rendering. Learn more by reading the `app/` directory (beta) documentation:
+
+- [Streaming and Suspense](https://beta.nextjs.org/docs/data-fetching/streaming-and-suspense)
+- [Instant Loading UI](https://beta.nextjs.org/docs/routing/loading-ui)
+
+[Deploy the `app/` directory example](https://vercel.com/templates/next.js/app-directory) to try Streaming SSR.
+
+## React Server Components
+
+In Next.js 13, you can start using the `app/` directory (beta) which use Server Components by default. Learn more by reading the `app/` directory (beta) documentation:
+
+- [Rendering Fundamentals](https://beta.nextjs.org/docs/rendering/fundamentals)
+- [Server and Client Components](https://beta.nextjs.org/docs/rendering/server-and-client-components)
+
+[Deploy the `app/` directory example](https://vercel.com/templates/next.js/app-directory) to try Server Components.
+
+## Edge and Node.js Runtimes
+
+Next.js has two **server runtimes** where you can render parts of your application code: the **Node.js Runtime** and the [**Edge Runtime**](/docs/api-reference/edge-runtime.md). Depending on your deployment infrastructure, both runtimes support streaming.
+
+By default, Next.js uses the Node.js runtime. [Middleware](https://nextjs.org/docs/advanced-features/middleware) and [Edge API Routes](https://nextjs.org/docs/api-routes/edge-api-routes) use the Edge runtime.
+
+[Learn more about the different runtimes](/docs/advanced-features/react-18/switchable-runtime.md).
diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md
new file mode 100644
index 0000000000000..c171b541a77e4
--- /dev/null
+++ b/docs/advanced-features/react-18/server-components.md
@@ -0,0 +1,10 @@
+# React Server Components
+
+React Server Components allow developers to build applications that span the server and client, combining the rich interactivity of client-side apps with the improved performance of traditional server rendering.
+
+In Next.js 13, you can start using the `app/` directory (beta) which use Server Components by default. Learn more by reading the `app/` directory (beta) documentation:
+
+- [Rendering Fundamentals](https://beta.nextjs.org/docs/rendering/fundamentals)
+- [Server and Client Components](https://beta.nextjs.org/docs/rendering/server-and-client-components)
+
+[Deploy the `app/` directory example](https://vercel.com/templates/next.js/app-directory) to try Server Components.
diff --git a/docs/advanced-features/react-18/streaming.md b/docs/advanced-features/react-18/streaming.md
new file mode 100644
index 0000000000000..89c327e8ebc80
--- /dev/null
+++ b/docs/advanced-features/react-18/streaming.md
@@ -0,0 +1,10 @@
+# Streaming SSR
+
+Streaming allows you to incrementally render parts of your UI to the client.
+
+In Next.js 13, you can start using the `app/` directory (beta) to take advantage of streaming server-rendering. Learn more by reading the `app/` directory (beta) documentation:
+
+- [Streaming and Suspense](https://beta.nextjs.org/docs/data-fetching/streaming-and-suspense)
+- [Instant Loading UI](https://beta.nextjs.org/docs/routing/loading-ui)
+
+[Deploy the `app/` directory example](https://vercel.com/templates/next.js/app-directory) to try Streaming SSR.
diff --git a/docs/advanced-features/react-18/switchable-runtime.md b/docs/advanced-features/react-18/switchable-runtime.md
new file mode 100644
index 0000000000000..cdd5268e825dd
--- /dev/null
+++ b/docs/advanced-features/react-18/switchable-runtime.md
@@ -0,0 +1,93 @@
+---
+description: Learn more about the switchable runtimes (Edge and Node.js) in Next.js.
+---
+
+# Edge and Node.js Runtimes
+
+Next.js has two **server runtimes** where you can render parts of your application code: the **Node.js Runtime** and the [**Edge Runtime**](/docs/api-reference/edge-runtime.md). Depending on your deployment infrastructure, both runtimes support streaming.
+
+By default, Next.js uses the Node.js runtime. [Middleware](https://nextjs.org/docs/advanced-features/middleware) and [Edge API Routes](https://nextjs.org/docs/api-routes/edge-api-routes) use the Edge runtime.
+
+## Global Runtime Option
+
+To configure the runtime for your whole application, you can set the experimental option `runtime` in your `next.config.js` file:
+
+```js
+// next.config.js
+module.exports = {
+ experimental: {
+ runtime: 'experimental-edge', // 'node.js' (default) | experimental-edge
+ },
+}
+```
+
+You can detect which runtime you're using by looking at the `process.env.NEXT_RUNTIME` Environment Variable during runtime, and examining the `options.nextRuntime` variable during compilation.
+
+## Page Runtime Option
+
+On each page, you can optionally export a `runtime` config set to either `'nodejs'` or `'experimental-edge'`:
+
+```jsx
+// pages/index.js
+export default function Index () { ... }
+
+export function getServerSideProps() { ... }
+
+export const config = {
+ runtime: 'experimental-edge',
+}
+```
+
+When both the per-page runtime and global runtime are set, the per-page runtime overrides the global runtime. If the per-page runtime is _not_ set, the global runtime option will be used.
+
+## Runtime Differences
+
+| | Node (Server) | Node (Serverless) | Edge |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------- | ---------------- |
+| [Cold Boot](https://vercel.com/docs/concepts/get-started/compute#cold-and-hot-boots?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) | / | ~250ms | Instant |
+| HTTP Streaming | Yes | Yes | Yes |
+| IO | All | All | `fetch` |
+| Scalability | / | High | Highest |
+| Security | Normal | High | High |
+| Latency | Normal | Low | Lowest |
+| Code Size | / | 50MB | 1MB |
+| NPM Packages | All | All | A smaller subset |
+
+Next.js' default runtime configuration is good for most use cases, but there’re still many reasons to change to one runtime over the other one.
+
+For example, for API routes that rely on native Node.js APIs, they need to run with the Node.js Runtime. However, if an API only uses something like cookie-based authentication, using Middleware and the Edge Runtime will be a better choice due to its lower latency as well as better scalability.
+
+## Edge API Routes
+
+[Edge API Routes](/docs/api-routes/edge-api-routes.md) enable you to build high performance APIs with Next.js using the Edge Runtime.
+
+```typescript
+export const config = {
+ runtime: 'experimental-edge',
+}
+
+export default (req) => new Response('Hello world!')
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/edge-runtime.md">
+ <b>Edge Runtime</b>
+ <small>Learn more about the supported Web APIs available.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-reference/next/server.md">
+ <b>Middleware API Reference</b>
+ <small>Learn more about the supported APIs for Middleware.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-routes/edge-api-routes.md">
+ <b>Edge API Routes</b>
+ <small>Build high performance APIs in Next.js. </small>
+ </a>
+</div>
diff --git a/docs/advanced-features/security-headers.md b/docs/advanced-features/security-headers.md
new file mode 100644
index 0000000000000..1e055400f3348
--- /dev/null
+++ b/docs/advanced-features/security-headers.md
@@ -0,0 +1,158 @@
+---
+description: Improve the security of your Next.js application by adding HTTP response headers.
+---
+
+# Security Headers
+
+To improve the security of your application, you can use [`headers`](/docs/api-reference/next.config.js/headers.md) in `next.config.js` to apply HTTP response headers to all routes in your application.
+
+```jsx
+// next.config.js
+
+// You can choose which headers to add to the list
+// after learning more below.
+const securityHeaders = []
+
+module.exports = {
+ async headers() {
+ return [
+ {
+ // Apply these headers to all routes in your application.
+ source: '/:path*',
+ headers: securityHeaders,
+ },
+ ]
+ },
+}
+```
+
+## Options
+
+### [X-DNS-Prefetch-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control)
+
+This header controls DNS prefetching, allowing browsers to proactively perform domain name resolution on external links, images, CSS, JavaScript, and more. This prefetching is performed in the background, so the [DNS](https://developer.mozilla.org/en-US/docs/Glossary/DNS) is more likely to be resolved by the time the referenced items are needed. This reduces latency when the user clicks a link.
+
+```jsx
+{
+ key: 'X-DNS-Prefetch-Control',
+ value: 'on'
+}
+```
+
+### [Strict-Transport-Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security)
+
+This header 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`](/docs/api-reference/next.config.js/headers.md) in your `next.config.js`.
+
+```jsx
+{
+ key: 'Strict-Transport-Security',
+ value: 'max-age=63072000; includeSubDomains; preload'
+}
+```
+
+### [X-XSS-Protection](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection)
+
+This header stops pages from loading when they detect reflected cross-site scripting (XSS) attacks. Although this protection is not necessary when sites implement a strong [`Content-Security-Policy`](#content-security-policy) disabling the use of inline JavaScript (`'unsafe-inline'`), it can still provide protection for older web browsers that don't support CSP.
+
+```jsx
+{
+ key: 'X-XSS-Protection',
+ value: '1; mode=block'
+}
+```
+
+### [X-Frame-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options)
+
+This header 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.
+
+```jsx
+{
+ key: 'X-Frame-Options',
+ value: 'SAMEORIGIN'
+}
+```
+
+### [Permissions-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy)
+
+This header allows you to control which features and APIs can be used in the browser. It was previously named `Feature-Policy`. You can view the full list of permission options [here](https://www.w3.org/TR/permissions-policy-1/).
+
+```jsx
+{
+ key: 'Permissions-Policy',
+ value: 'camera=(), microphone=(), geolocation=(), browsing-topics=()'
+}
+```
+
+### [X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options)
+
+This header prevents the browser from attempting to guess the type of content if the `Content-Type` header is not explicitly set. This can prevent XSS exploits for websites that allow users to upload and share files. For example, a user trying to download an image, but having it treated as a different `Content-Type` like an executable, which could be malicious. This header also applies to downloading browser extensions. The only valid value for this header is `nosniff`.
+
+```jsx
+{
+ key: 'X-Content-Type-Options',
+ value: 'nosniff'
+}
+```
+
+### [Referrer-Policy](https://scotthelme.co.uk/a-new-security-header-referrer-policy/)
+
+This header controls how much information the browser includes when navigating from the current website (origin) to another. You can read about the different options [here](https://scotthelme.co.uk/a-new-security-header-referrer-policy/).
+
+```jsx
+{
+ key: 'Referrer-Policy',
+ value: 'origin-when-cross-origin'
+}
+```
+
+### [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+
+This header helps prevent cross-site scripting (XSS), clickjacking and other code injection attacks. Content Security Policy (CSP) can specify allowed origins for content including scripts, stylesheets, images, fonts, objects, media (audio, video), iframes, and more.
+
+You can read about the many different CSP options [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP).
+
+You can add Content Security Policy directives using a template string.
+
+```jsx
+// Before defining your Security Headers
+// add Content Security Policy directives using a template string.
+
+const ContentSecurityPolicy = `
+ default-src 'self';
+ script-src 'self';
+ child-src example.com;
+ style-src 'self' example.com;
+ font-src 'self';
+`
+```
+
+When a directive uses a keyword such as `self`, wrap it in single quotes `''`.
+
+In the header's value, replace the new line with a space.
+
+```js
+{
+ key: 'Content-Security-Policy',
+ value: ContentSecurityPolicy.replace(/\s{2,}/g, ' ').trim()
+}
+```
+
+### References
+
+- [MDN](https://developer.mozilla.org)
+- [Varun Naik](https://blog.vnaik.com/posts/web-attacks.html)
+- [Scott Helme](https://scotthelme.co.uk)
+- [Mozilla Observatory](https://observatory.mozilla.org/)
+
+## Related
+
+For more information, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/headers.md">
+ <b>Headers:</b>
+ <small>Add custom HTTP headers to your Next.js app.</small>
+ </a>
+</div>
diff --git a/docs/advanced-features/source-maps.md b/docs/advanced-features/source-maps.md
new file mode 100644
index 0000000000000..d17554ace41fc
--- /dev/null
+++ b/docs/advanced-features/source-maps.md
@@ -0,0 +1,25 @@
+---
+description: Enables browser source map generation during the production build.
+---
+
+# Source Maps
+
+Source Maps are enabled by default during development. During production builds, they are disabled to prevent you leaking your source on the client, unless you specifically opt in with the configuration flag.
+
+## Configuration flag
+
+Next.js provides a configuration flag you can use to enable browser source map generation during the production build:
+
+```js
+// next.config.js
+module.exports = {
+ productionBrowserSourceMaps: true,
+}
+```
+
+When the `productionBrowserSourceMaps` option is enabled, the source maps will be output in the same directory as the JavaScript files. Next.js will automatically serve these files when requested.
+
+## Caveats
+
+- Adding source maps can increase `next build` time
+- Increases memory usage during `next build`
diff --git a/docs/advanced-features/src-directory.md b/docs/advanced-features/src-directory.md
new file mode 100644
index 0000000000000..6bb496833fd59
--- /dev/null
+++ b/docs/advanced-features/src-directory.md
@@ -0,0 +1,25 @@
+---
+description: Save pages under the `src` directory as an alternative to the root `pages` directory.
+---
+
+# `src` Directory
+
+Pages can also be added under `src/pages` as an alternative to the root `pages` directory.
+
+The `src` directory is very common in many apps and Next.js supports it by default.
+
+## Caveats
+
+- `src/pages` will be ignored if `pages` is present in the root directory
+- Config files like `next.config.js` and `tsconfig.json`, as well as environment variables, should be inside the root directory, moving them to `src` won't work. Same goes for the [`public` directory](/docs/basic-features/static-file-serving.md)
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/basic-features/pages.md">
+ <b>Pages:</b>
+ <small>Learn more about what pages are in Next.js</small>
+ </a>
+</div>
diff --git a/docs/advanced-features/static-html-export.md b/docs/advanced-features/static-html-export.md
new file mode 100644
index 0000000000000..426a009edd040
--- /dev/null
+++ b/docs/advanced-features/static-html-export.md
@@ -0,0 +1,74 @@
+---
+description: Export your Next.js app to static HTML, and run it standalone without the need of a Node.js server.
+---
+
+# Static HTML Export
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-static-export">Static Export</a></li>
+ </ul>
+</details>
+
+`next export` allows you to export your Next.js application to static HTML, which can be run standalone without the need of a Node.js server. It is recommended to only use `next export` if you don't need any of the [unsupported features](#unsupported-features) requiring a server.
+
+If you're looking to build a hybrid site where only _some_ pages are prerendered to static HTML, Next.js already does that automatically. Learn more about [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) and [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md).
+
+## `next export`
+
+Update your build script in `package.json` to use `next export`:
+
+```json
+"scripts": {
+ "build": "next build && next export"
+}
+```
+
+Running `npm run build` will generate an `out` directory.
+
+`next export` builds an HTML version of your app. During `next build`, [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) and [`getStaticPaths`](/docs/basic-features/data-fetching/get-static-paths.md) will generate an HTML file for each page in your `pages` directory (or more for [dynamic routes](/docs/routing/dynamic-routes.md)). Then, `next export` will copy the already exported files into the correct directory. `getInitialProps` will generate the HTML files during `next export` instead of `next build`.
+
+For more advanced scenarios, you can define a parameter called [`exportPathMap`](/docs/api-reference/next.config.js/exportPathMap.md) in your [`next.config.js`](/docs/api-reference/next.config.js/introduction.md) file to configure exactly which pages will be generated.
+
+> **Warning**: Using `exportPathMap` for defining routes with any `getStaticPaths` powered page is now ignored and gets overridden. We recommend not to use them together.
+
+## Supported Features
+
+The majority of core Next.js features needed to build a static site are supported, including:
+
+- [Dynamic Routes when using `getStaticPaths`](/docs/routing/dynamic-routes.md)
+- Prefetching with `next/link`
+- Preloading JavaScript
+- [Dynamic Imports](/docs/advanced-features/dynamic-import.md)
+- Any styling options (e.g. CSS Modules, styled-jsx)
+- [Client-side data fetching](/docs/basic-features/data-fetching/client-side.md)
+- [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md)
+- [`getStaticPaths`](/docs/basic-features/data-fetching/get-static-paths.md)
+- [Image Optimization](/docs/basic-features/image-optimization.md) using a [custom loader](/docs/basic-features/image-optimization.md#loaders)
+
+## Unsupported Features
+
+Features that require a Node.js server, or dynamic logic that cannot be computed during the build process, are not supported:
+
+- [Image Optimization](/docs/basic-features/image-optimization.md) (default loader)
+- [Internationalized Routing](/docs/advanced-features/i18n-routing.md)
+- [API Routes](/docs/api-routes/introduction.md)
+- [Rewrites](/docs/api-reference/next.config.js/rewrites.md)
+- [Redirects](/docs/api-reference/next.config.js/redirects.md)
+- [Headers](/docs/api-reference/next.config.js/headers.md)
+- [Middleware](/docs/middleware.md)
+- [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md)
+- [`fallback: true`](/docs/api-reference/data-fetching/get-static-paths.md#fallback-true)
+- [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md)
+
+### `getInitialProps`
+
+It's possible to use the [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md) API instead of `getStaticProps`, but it comes with a few caveats:
+
+- `getInitialProps` cannot be used alongside `getStaticProps` or `getStaticPaths` on any given page. If you have dynamic routes, instead of using `getStaticPaths` you'll need to configure the [`exportPathMap`](/docs/api-reference/next.config.js/exportPathMap.md) parameter in your [`next.config.js`](/docs/api-reference/next.config.js/introduction.md) file to let the exporter know which HTML files it should output.
+- When `getInitialProps` is called during export, the `req` and `res` fields of its [`context`](/docs/api-reference/data-fetching/get-initial-props.md#context-object) parameter will be empty objects, since during export there is no server running.
+- `getInitialProps` **will be called on every client-side navigation**, if you'd like to only fetch data at build-time, switch to `getStaticProps`.
+- `getInitialProps` should fetch from an API and cannot use Node.js-specific libraries or the file system like `getStaticProps` can.
+
+We recommend migrating towards `getStaticProps` over `getInitialProps` whenever possible.
diff --git a/docs/advanced-features/turbopack.md b/docs/advanced-features/turbopack.md
new file mode 100644
index 0000000000000..7f1b7ad77deba
--- /dev/null
+++ b/docs/advanced-features/turbopack.md
@@ -0,0 +1,29 @@
+---
+description: Turbopack (alpha) can be used inside Next.js 13 for 700x faster updatse.
+---
+
+# Turbopack (alpha)
+
+[Turbopack](https://turbo.build/pack) is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js 13.
+
+On large applications Turbopack updates 10x faster than Vite and 700x faster than Webpack. For the biggest applications, the difference is even larger with updates up to 20x faster than Vite.
+
+## Usage
+
+Turbopack can be used in Next.js 13 in both the `pages` and `app` directories:
+
+1. Create a Next.js 13 project with Turbopack
+
+```bash
+npx create-next-app@latest --example with-turbopack
+```
+
+2. Start the Next.js development server (with Turbopack)
+
+```bash
+next dev --turbo
+```
+
+## Supported Features
+
+To learn more about the currently supported features for Turbopack, view the [documentation](https://turbo.build/pack/docs/features).
diff --git a/docs/advanced-features/using-mdx.md b/docs/advanced-features/using-mdx.md
new file mode 100644
index 0000000000000..a66484477d23f
--- /dev/null
+++ b/docs/advanced-features/using-mdx.md
@@ -0,0 +1,228 @@
+---
+description: Learn how to use @next/mdx in your Next.js project.
+---
+
+# Using MDX with Next.js
+
+MDX is a superset of markdown that lets you write JSX directly in your markdown files. It is a powerful way to add dynamic interactivity, and embed components within your content, helping you to bring your pages to life.
+
+Next.js supports MDX through a number of different means, this page will outline some of the ways you can begin integrating MDX into your Next.js project.
+
+## Why use MDX?
+
+Authoring in markdown is an intuitive way to write content, its terse syntax, once adopted, can enable you to write content that is both readable and maintainable. Because you can use `HTML` elements in your markdown, you can also get creative when styling your markdown pages.
+
+However, because markdown is essentially static content, you can't create _dynamic_ content based on user interactivity. Where MDX shines is in its ability to let you create and use your React components directly in the markup. This opens up a wide range of possibilities when composing your sites pages with interactivity in mind.
+
+## MDX Plugins
+
+Internally MDX uses remark and rehype. Remark is a markdown processor powered by a plugins ecosystem. This plugin ecosystem lets you parse code, transform `HTML` elements, change syntax, extract frontmatter, and more. Using [remark-gfm to enable GitHub flavored markdown (GFM)](https://mdxjs.com/guides/gfm/) is a popular option.
+
+Rehype is an `HTML` processor, also powered by a plugin ecosystem. Similar to remark, these plugins let you manipulate, sanitize, compile and configure all types of data, elements and content.
+
+To use a plugin from either remark or rehype, you will need to add it to the MDX packages config.
+
+## `@next/mdx`
+
+The `@next/mdx` package is configured in the `next.config.js` file at your projects root. **It sources data from local files**, allowing you to create pages with a `.mdx` extension, directly in your `/pages` directory.
+
+### Setup `@next/mdx` in Next.js
+
+The following steps outline how to setup `@next/mdx` in your Next.js project:
+
+1. Install the required packages:
+
+ ```bash
+ npm install @next/mdx @mdx-js/loader @mdx-js/react
+ ```
+
+2. Require the package and configure to support top level `.mdx` pages. The following adds the `options` object key allowing you to pass in any plugins:
+
+ ```js
+ // next.config.js
+
+ const withMDX = require('@next/mdx')({
+ extension: /\.mdx?$/,
+ options: {
+ // If you use remark-gfm, you'll need to use next.config.mjs
+ // as the package is ESM only
+ // https://github.com/remarkjs/remark-gfm#install
+ remarkPlugins: [],
+ rehypePlugins: [],
+ // If you use `MDXProvider`, uncomment the following line.
+ // providerImportSource: "@mdx-js/react",
+ },
+ })
+ module.exports = withMDX({
+ // Append the default value with md extensions
+ pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
+ })
+ ```
+
+3. Create a new MDX page within the `/pages` directory:
+
+ ```bash
+ - /pages
+ - my-mdx-page.mdx
+ - package.json
+ ```
+
+## Using Components, Layouts and Custom Elements
+
+You can now import a React component directly inside your MDX page:
+
+```md
+import { MyComponent } from 'my-components'
+
+# My MDX page
+
+This is a list in markdown:
+
+- One
+- Two
+- Three
+
+Checkout my React component:
+
+<MyComponent/>
+```
+
+### Frontmatter
+
+Frontmatter is a YAML like key/value pairing that can be used to store data about a page. `@next/mdx` does **not** support frontmatter by default, though there are many solutions for adding frontmatter to your MDX content, such as [gray-matter](https://github.com/jonschlinkert/gray-matter).
+
+To access page metadata with `@next/mdx`, you can export a meta object from within the `.mdx` file:
+
+```md
+export const meta = {
+author: 'Rich Haines'
+}
+
+# My MDX page
+```
+
+### Layouts
+
+To add a layout to your MDX page, create a new component and import it into the MDX page. Then you can wrap the MDX page with your layout component:
+
+```md
+import { MyComponent, MyLayoutComponent } from 'my-components'
+
+export const meta = {
+author: 'Rich Haines'
+}
+
+# My MDX Page with a Layout
+
+This is a list in markdown:
+
+- One
+- Two
+- Three
+
+Checkout my React component:
+
+<MyComponent/>
+
+export default ({ children }) => <MyLayoutComponent meta={meta}>{children}</MyLayoutComponent>
+```
+
+### Custom Elements
+
+One of the pleasant aspects of using markdown, is that it maps to native `HTML` elements, making writing fast, and intuitive:
+
+```md
+# H1 heading
+
+## H2 heading
+
+This is a list in markdown:
+
+- One
+- Two
+- Three
+```
+
+The above generates the following `HTML`:
+
+```html
+<h1>H1 heading</h1>
+
+<h2>H2 heading</h2>
+
+<p>This is a list in markdown:</p>
+
+<ul>
+ <li>One</li>
+ <li>Two</li>
+ <li>Three</li>
+</ul>
+```
+
+When you want to style your own elements to give a custom feel to your website or application, you can pass in shortcodes. These are your own custom components that map to `HTML` elements. To do this you use the `MDXProvider` and pass a components object as a prop. Each object key in the components object maps to a `HTML` element name.
+
+To enable you need to specify `providerImportSource: "@mdx-js/react"` in `next.config.js`.
+
+```js
+// next.config.js
+
+const withMDX = require('@next/mdx')({
+ // ...
+ options: {
+ providerImportSource: '@mdx-js/react',
+ },
+})
+```
+
+Then setup the provider in your page
+
+```jsx
+// pages/index.js
+
+import { MDXProvider } from '@mdx-js/react'
+import Image from 'next/image'
+import { Heading, InlineCode, Pre, Table, Text } from 'my-components'
+
+const ResponsiveImage = (props) => (
+ <Image alt={props.alt} layout="responsive" {...props} />
+)
+
+const components = {
+ img: ResponsiveImage,
+ h1: Heading.H1,
+ h2: Heading.H2,
+ p: Text,
+ pre: Pre,
+ code: InlineCode,
+}
+
+export default function Post(props) {
+ return (
+ <MDXProvider components={components}>
+ <main {...props} />
+ </MDXProvider>
+ )
+}
+```
+
+If you use it across the site you may want to add the provider to `_app.js` so all MDX pages pick up the custom element config.
+
+## Using rust based MDX compiler (experimental)
+
+Next.js supports a new MDX compiler written in Rust. This compiler is still experimental and is not recommended for production use. To use the new compiler, you need to configure `next.config.js` when you pass it to `withMDX`:
+
+```js
+// next.config.js
+module.exports = withMDX({
+ experimental: {
+ mdxRs: true,
+ },
+})
+```
+
+## Helpful Links
+
+- [MDX](https://mdxjs.com)
+- [`@next/mdx`](https://www.npmjs.com/package/@next/mdx)
+- [remark](https://github.com/remarkjs/remark)
+- [rehype](https://github.com/rehypejs/rehype)
diff --git a/docs/api-reference/cli.md b/docs/api-reference/cli.md
new file mode 100644
index 0000000000000..a1baeacccf5b6
--- /dev/null
+++ b/docs/api-reference/cli.md
@@ -0,0 +1,172 @@
+---
+description: The Next.js CLI allows you to start, build, and export your application. Learn more about it here.
+---
+
+# Next.js CLI
+
+The Next.js CLI allows you to start, build, and export your application.
+
+To get a list of the available CLI commands, run the following command inside your project directory:
+
+```bash
+npx next -h
+```
+
+_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher)_
+
+The output should look like this:
+
+```bash
+Usage
+ $ next <command>
+
+Available commands
+ build, start, export, dev, lint, telemetry, info
+
+Options
+ --version, -v Version number
+ --help, -h Displays this message
+
+For more information run a command with the --help flag
+ $ next build --help
+```
+
+You can pass any [node arguments](https://nodejs.org/api/cli.html#cli_node_options_options) to `next` commands:
+
+```bash
+NODE_OPTIONS='--throw-deprecation' next
+NODE_OPTIONS='-r esm' next
+NODE_OPTIONS='--inspect' next
+```
+
+> Note: Running `next` without a command is the same as running `next dev`
+
+## Build
+
+`next build` creates an optimized production build of your application. The output displays information about each route.
+
+- **Size** – The number of assets downloaded when navigating to the page client-side. The size for each route only includes its dependencies.
+- **First Load JS** – The number of assets downloaded when visiting the page from the server. The amount of JS shared by all is shown as a separate metric.
+
+Both of these values are **compressed with gzip**. The first load is indicated by green, yellow, or red. Aim for green for performant applications.
+
+You can enable production profiling for React with the `--profile` flag in `next build`. This requires [Next.js 9.5](https://nextjs.org/blog/next-9-5):
+
+```bash
+next build --profile
+```
+
+After that, you can use the profiler in the same way as you would in development.
+
+You can enable more verbose build output with the `--debug` flag in `next build`. This requires Next.js 9.5.3:
+
+```bash
+next build --debug
+```
+
+With this flag enabled additional build output like rewrites, redirects, and headers will be shown.
+
+## Development
+
+`next dev` starts the application in development mode with hot-code reloading, error reporting, and more:
+
+The application will start at `http://localhost:3000` by default. The default port can be changed with `-p`, like so:
+
+```bash
+npx next dev -p 4000
+```
+
+Or using the `PORT` environment variable:
+
+```bash
+PORT=4000 npx next dev
+```
+
+> Note: `PORT` can not be set in `.env` as booting up the HTTP server happens before any other code is initialized.
+
+You can also set the hostname to be different from the default of `0.0.0.0`, this can be useful for making the application available for other devices on the network. The default hostname can be changed with `-H`, like so:
+
+```bash
+npx next dev -H 192.168.1.2
+```
+
+## Production
+
+`next start` starts the application in production mode. The application should be compiled with [`next build`](#build) first.
+
+The application will start at `http://localhost:3000` by default. The default port can be changed with `-p`, like so:
+
+```bash
+npx next start -p 4000
+```
+
+Or using the `PORT` environment variable:
+
+```bash
+PORT=4000 npx next start
+```
+
+> Note: `PORT` can not be set in `.env` as booting up the HTTP server happens before any other code is initialized.
+
+### Keep Alive Timeout
+
+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.
+
+To configure the timeout values for the production Next.js server, pass `--keepAliveTimeout` (in milliseconds) to `next start`, like so:
+
+```bash
+npx next start --keepAliveTimeout 70000
+```
+
+## Lint
+
+`next lint` runs ESLint for all files in the `pages`, `components`, and `lib` directories. It also
+provides a guided setup to install any required dependencies if ESLint is not already configured in
+your application.
+
+If you have other directories that you would like to lint, you can specify them using the `--dir`
+flag:
+
+```bash
+next lint --dir utils
+```
+
+## Telemetry
+
+Next.js collects **completely anonymous** telemetry data about general usage.
+Participation in this anonymous program is optional, and you may opt-out if you'd not like to share any information.
+
+To learn more about Telemetry, [please read this document](https://nextjs.org/telemetry/).
+
+## Info
+
+`next info` prints relevant details about the current system which can be used to report Next.js bugs.
+This information includes Operating System platform/arch/version, Binaries (Node.js, npm, Yarn, pnpm) and npm package versions (`next`, `react`, `react-dom`).
+
+Running the following in your project's root directory:
+
+```bash
+next info
+```
+
+will give you information like this example:
+
+```bash
+
+ Operating System:
+ Platform: linux
+ Arch: x64
+ Version: #22-Ubuntu SMP Fri Nov 5 13:21:36 UTC 2021
+ Binaries:
+ Node: 16.13.0
+ npm: 8.1.0
+ Yarn: 1.22.17
+ pnpm: 6.24.2
+ Relevant packages:
+ next: 12.0.8
+ react: 17.0.2
+ react-dom: 17.0.2
+
+```
+
+This information should then be pasted into GitHub Issues.
diff --git a/docs/api-reference/create-next-app.md b/docs/api-reference/create-next-app.md
new file mode 100644
index 0000000000000..3654c69a11d98
--- /dev/null
+++ b/docs/api-reference/create-next-app.md
@@ -0,0 +1,115 @@
+---
+description: Create Next.js apps in one command with create-next-app.
+---
+
+# Create Next App
+
+The easiest way to get started with Next.js is by using `create-next-app`. This CLI tool enables you to quickly start building a new Next.js application, with everything set up for you. You can create a new app using the default Next.js template, or by using one of the [official Next.js examples](https://github.com/vercel/next.js/tree/canary/examples). To get started, use the following command:
+
+### Interactive
+
+You can create a new project interactively by running:
+
+```bash
+npx create-next-app@latest
+# or
+yarn create next-app
+# or
+pnpm create next-app
+```
+
+You will be asked for the name of your project, and then whether you want to
+create a TypeScript project:
+
+```bash
+✔ Would you like to use TypeScript with this project? … No / Yes
+```
+
+Select **Yes** to install the necessary types/dependencies and create a new TS project.
+
+### Non-interactive
+
+You can also pass command line arguments to set up a new project
+non-interactively. See `create-next-app --help`:
+
+```bash
+create-next-app <project-directory> [options]
+
+Options:
+ -V, --version output the version number
+ --ts, --typescript
+
+ Initialize as a TypeScript project. (default)
+
+ --js, --javascript
+
+ Initialize as a JavaScript project.
+
+ --eslint
+
+ Initialize with eslint config.
+
+ --no-eslint
+
+ Initialize without eslint config.
+
+ --experimental-app
+
+ Initialize as a `app/` directory project.
+
+ --use-npm
+
+ Explicitly tell the CLI to bootstrap the app using npm
+
+ --use-pnpm
+
+ Explicitly tell the CLI to bootstrap the app using pnpm
+
+ -e, --example [name]|[github-url]
+
+ An example to bootstrap the app with. You can use an example name
+ from the official Next.js repo or a GitHub URL. The URL can use
+ any branch and/or subdirectory
+
+ --example-path <path-to-example>
+
+ In a rare case, your GitHub URL might contain a branch name with
+ a slash (e.g. bug/fix-1) and the path to the example (e.g. foo/bar).
+ In this case, you must specify the path to the example separately:
+ --example-path foo/bar
+```
+
+### Why use Create Next App?
+
+`create-next-app` allows you to create a new Next.js app within seconds. It is officially maintained by the creators of Next.js, and includes a number of benefits:
+
+- **Interactive Experience**: Running `npx create-next-app@latest` (with no arguments) launches an interactive experience that guides you through setting up a project.
+- **Zero Dependencies**: Initializing a project is as quick as one second. Create Next App has zero dependencies.
+- **Offline Support**: Create Next App will automatically detect if you're offline and bootstrap your project using your local package cache.
+- **Support for Examples**: Create Next App can bootstrap your application using an example from the Next.js examples collection (e.g. `npx create-next-app --example api-routes`).
+- **Tested**: The package is part of the Next.js monorepo and tested using the same integration test suite as Next.js itself, ensuring it works as expected with every release.
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/basic-features/pages.md">
+ <b>Pages:</b>
+ <small>Learn more about what pages are in Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/basic-features/built-in-css-support.md">
+ <b>CSS Support:</b>
+ <small>Use the built-in CSS support to add custom styles to your app.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-reference/cli.md">
+ <b>CLI:</b>
+ <small>Learn more about the Next.js CLI.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/data-fetching/get-initial-props.md b/docs/api-reference/data-fetching/get-initial-props.md
new file mode 100644
index 0000000000000..5bf23570dd175
--- /dev/null
+++ b/docs/api-reference/data-fetching/get-initial-props.md
@@ -0,0 +1,130 @@
+---
+description: Enable Server-Side Rendering in a page and do initial data population with `getInitialProps`.
+---
+
+# getInitialProps
+
+> **Note**: Next.js 13 introduces the `app/` directory (beta). This new directory has support for [colocated data fetching](https://beta.nextjs.org/docs/data-fetching/fundamentals) at the component level, using the new React `use` hook and an extended `fetch` Web API.
+>
+> [Learn more about incrementally adopting `app/`](https://beta.nextjs.org/docs/upgrade-guide).
+
+`getInitialProps` enables [server-side rendering](/docs/basic-features/pages.md#server-side-rendering) in a page and allows you to do **initial data population**, it means sending the [page](/docs/basic-features/pages.md) with the data already populated from the server. This is especially useful for [SEO](https://en.wikipedia.org/wiki/Search_engine_optimization).
+
+`getInitialProps` will disable [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
+
+`getInitialProps` is an `async` function that can be added to any page as a [`static method`](https://javascript.info/static-properties-methods). Take a look at the following example:
+
+```jsx
+function Page({ stars }) {
+ return <div>Next stars: {stars}</div>
+}
+
+Page.getInitialProps = async (ctx) => {
+ const res = await fetch('https://api.github.com/repos/vercel/next.js')
+ const json = await res.json()
+ return { stars: json.stargazers_count }
+}
+
+export default Page
+```
+
+Or using a class component:
+
+```jsx
+import React from 'react'
+
+class Page extends React.Component {
+ static async getInitialProps(ctx) {
+ const res = await fetch('https://api.github.com/repos/vercel/next.js')
+ const json = await res.json()
+ return { stars: json.stargazers_count }
+ }
+
+ render() {
+ return <div>Next stars: {this.props.stars}</div>
+ }
+}
+
+export default Page
+```
+
+`getInitialProps` is used to asynchronously fetch some data, which then populates `props`.
+
+Data returned from `getInitialProps` is serialized when server rendering, similar to what [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) does. Make sure the returned object from `getInitialProps` is a plain `Object` and not using `Date`, `Map` or `Set`.
+
+For the initial page load, `getInitialProps` will run on the server only. `getInitialProps` will then run on the client when navigating to a different route via the [`next/link`](/docs/api-reference/next/link.md) component or by using [`next/router`](/docs/api-reference/next/router.md). However, if `getInitialProps` is used in a custom `_app.js`, and the page being navigated to implements `getServerSideProps`, then `getInitialProps` will run on the server.
+
+## Context Object
+
+`getInitialProps` receives a single argument called `context`, it's an object with the following properties:
+
+- `pathname` - Current route. That is the path of the page in `/pages`
+- `query` - Query string section of URL parsed as an object
+- `asPath` - `String` of the actual path (including the query) shown in the browser
+- `req` - [HTTP request object](https://nodejs.org/api/http.html#http_class_http_incomingmessage 'Class: http.IncomingMessage HTTP | Node.js v14.8.0 Documentation') (server only)
+- `res` - [HTTP response object](https://nodejs.org/api/http.html#http_class_http_serverresponse 'Class: http.ServerResponse HTTP | Node.js v14.8.0 Documentation') (server only)
+- `err` - Error object if any error is encountered during the rendering
+
+## Caveats
+
+- `getInitialProps` can **not** be used in children components, only in the default export of every page
+- If you are using server-side only modules inside `getInitialProps`, make sure to [import them properly](https://arunoda.me/blog/ssr-and-server-only-modules), otherwise it'll slow down your app
+
+> Note that irrespective of rendering type, any `props` will be passed to the page component and can be viewed on the client-side in the initial HTML. This is to allow the page to be [hydrated](https://reactjs.org/docs/react-dom.html#hydrate) correctly. Make sure that you don't pass any sensitive information that shouldn't be available on the client in `props`.
+
+## TypeScript
+
+If you're using TypeScript, you can use the `NextPage` type for function components:
+
+```jsx
+import { NextPage } from 'next'
+
+interface Props {
+ userAgent?: string;
+}
+
+const Page: NextPage<Props> = ({ userAgent }) => (
+ <main>Your user agent: {userAgent}</main>
+)
+
+Page.getInitialProps = async ({ req }) => {
+ const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
+ return { userAgent }
+}
+
+export default Page
+```
+
+And for `React.Component`, you can use `NextPageContext`:
+
+```jsx
+import React from 'react'
+import { NextPageContext } from 'next'
+
+interface Props {
+ userAgent?: string;
+}
+
+export default class Page extends React.Component<Props> {
+ static async getInitialProps({ req }: NextPageContext) {
+ const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
+ return { userAgent }
+ }
+
+ render() {
+ const { userAgent } = this.props
+ return <main>Your user agent: {userAgent}</main>
+ }
+}
+```
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/basic-features/data-fetching/overview.md">
+ <b>Data Fetching:</b>
+ <small>Learn more about data fetching in Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/data-fetching/get-server-side-props.md b/docs/api-reference/data-fetching/get-server-side-props.md
new file mode 100644
index 0000000000000..689392ccd284e
--- /dev/null
+++ b/docs/api-reference/data-fetching/get-server-side-props.md
@@ -0,0 +1,190 @@
+---
+description: API reference for `getServerSideProps`. Learn how to fetch data on each request with Next.js.
+---
+
+# getServerSideProps
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | ------------------------------------------------------------------- |
+| `v10.0.0` | `locale`, `locales`, `defaultLocale`, and `notFound` options added. |
+| `v9.3.0` | `getServerSideProps` introduced. |
+
+</details>
+
+> **Note**: Next.js 13 introduces the `app/` directory (beta). This new directory has support for [colocated data fetching](https://beta.nextjs.org/docs/data-fetching/fundamentals) at the component level, using the new React `use` hook and an extended `fetch` Web API.
+>
+> [Learn more about incrementally adopting `app/`](https://beta.nextjs.org/docs/upgrade-guide).
+
+When exporting a function called `getServerSideProps` (Server-Side Rendering) from a page, Next.js will pre-render this page on each request using the data returned by `getServerSideProps`. This is useful if you want to fetch data that changes often, and have the page update to show the most current data.
+
+```js
+export async function getServerSideProps(context) {
+ return {
+ props: {}, // will be passed to the page component as props
+ }
+}
+```
+
+You can import modules in top-level scope for use in `getServerSideProps`. Imports used will **not be bundled for the client-side**. This means you can write **server-side code directly in `getServerSideProps`**, including fetching data from your database.
+
+## Context parameter
+
+The `context` parameter is an object containing the following keys:
+
+- `params`: If this page uses a [dynamic route](/docs/routing/dynamic-routes.md), `params` contains the route parameters. If the page name is `[id].js` , then `params` will look like `{ id: ... }`.
+- `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`: `preview` is `true` if the page is in the [Preview Mode](/docs/advanced-features/preview-mode.md) and `false` otherwise.
+- `previewData`: The [preview](/docs/advanced-features/preview-mode.md) data set by `setPreviewData`.
+- `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).
+- `defaultLocale` contains the configured default locale (if enabled).
+
+## getServerSideProps return values
+
+The `getServerSideProps` function should return an object with **any one of the following** properties:
+
+### `props`
+
+The `props` object is a key-value pair, where each value is received by the page component. It should be a [serializable object](https://developer.mozilla.org/en-US/docs/Glossary/Serialization) so that any props passed, could be serialized with [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
+
+```jsx
+export async function getServerSideProps(context) {
+ return {
+ props: { message: `Next.js is awesome` }, // will be passed to the page component as props
+ }
+}
+```
+
+### `notFound`
+
+The `notFound` boolean allows the page to return a `404` status and [404 Page](/docs/advanced-features/custom-error-page.md#404-page). With `notFound: true`, the page will return a `404` even if there was a successfully generated page before. This is meant to support use cases like user-generated content getting removed by its author.
+
+```js
+export async function getServerSideProps(context) {
+ const res = await fetch(`https://.../data`)
+ const data = await res.json()
+
+ if (!data) {
+ return {
+ notFound: true,
+ }
+ }
+
+ return {
+ props: { data }, // will be passed to the page component as props
+ }
+}
+```
+
+### `redirect`
+
+The `redirect` object allows redirecting to internal and external resources. It should match the shape of `{ destination: string, permanent: boolean }`. In some rare cases, you might need to assign a custom status code for older `HTTP` clients to properly redirect. In these cases, you can use the `statusCode` property instead of the `permanent` property, but not both.
+
+```js
+export async function getServerSideProps(context) {
+ const res = await fetch(`https://.../data`)
+ const data = await res.json()
+
+ if (!data) {
+ return {
+ redirect: {
+ destination: '/',
+ permanent: false,
+ },
+ }
+ }
+
+ return {
+ props: {}, // will be passed to the page component as props
+ }
+}
+```
+
+### getServerSideProps with TypeScript
+
+The type of `getServerSideProps` can be specified using `GetServerSideProps` from `next`:
+
+```ts
+import { GetServerSideProps } from 'next'
+
+type Data = { ... }
+
+export const getServerSideProps: GetServerSideProps<{ data: Data }> = async (context) => {
+ const res = await fetch('https://.../data')
+ const data: Data = await res.json()
+
+ return {
+ props: {
+ data,
+ },
+ }
+}
+```
+
+If you want to get inferred typings for your props, you can use `InferGetServerSidePropsType<typeof getServerSideProps>`:
+
+```tsx
+import { InferGetServerSidePropsType } from 'next'
+import { GetServerSideProps } from 'next'
+
+type Data = { ... }
+
+export const getServerSideProps: GetServerSideProps<{ data: Data }> = async () => {
+ const res = await fetch('https://.../data')
+ const data: Data = await res.json()
+
+ return {
+ props: {
+ data,
+ },
+ }
+}
+
+function Page({ data }: InferGetServerSidePropsType<typeof getServerSideProps>) {
+ // will resolve data to type Data
+}
+
+export default Page
+```
+
+Implicit typing for `getServerSideProps` will also work properly:
+
+```tsx
+import { InferGetServerSidePropsType } from 'next'
+
+type Data = { ... }
+
+export const getServerSideProps = async () => {
+ const res = await fetch('https://.../data')
+ const data: Data = await res.json()
+
+ return {
+ props: {
+ data,
+ },
+ }
+}
+
+function Page({ data }: InferGetServerSidePropsType<typeof getServerSideProps>) {
+ // will resolve data to type Data
+}
+
+export default Page
+```
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/basic-features/data-fetching/overview.md">
+ <b>Data Fetching:</b>
+ <small>Learn more about data fetching in Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/data-fetching/get-static-paths.md b/docs/api-reference/data-fetching/get-static-paths.md
new file mode 100644
index 0000000000000..c72851cdb63b5
--- /dev/null
+++ b/docs/api-reference/data-fetching/get-static-paths.md
@@ -0,0 +1,223 @@
+---
+description: API reference for `getStaticPaths`. Learn how to fetch data and generate static pages with `getStaticPaths`.
+---
+
+# getStaticPaths
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `v12.2.0` | [On-Demand Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md#on-demand-revalidation) is stable. |
+| `v12.1.0` | [On-Demand Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md#on-demand-revalidation) added (beta). |
+| `v9.5.0` | Stable [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md) |
+| `v9.3.0` | `getStaticPaths` introduced. |
+
+</details>
+
+When exporting a function called `getStaticPaths` from a page that uses [Dynamic Routes](/docs/routing/dynamic-routes.md), Next.js will statically pre-render all the paths specified by `getStaticPaths`.
+
+```jsx
+export async function getStaticPaths() {
+ return {
+ paths: [
+ { params: { ... } } // See the "paths" section below
+ ],
+ fallback: true, false or "blocking" // See the "fallback" section below
+ };
+}
+```
+
+## getStaticPaths return values
+
+The `getStaticPaths` function should return an object with the following **required** properties:
+
+### `paths`
+
+The `paths` key determines which paths will be pre-rendered. For example, suppose that you have a page that uses [Dynamic Routes](/docs/routing/dynamic-routes.md) named `pages/posts/[id].js`. If you export `getStaticPaths` from this page and return the following for `paths`:
+
+```js
+return {
+ paths: [
+ { params: { id: '1' }},
+ {
+ params: { id: '2' },
+ // with i18n configured the locale for the path can be returned as well
+ locale: "en",
+ },
+ ],
+ fallback: ...
+}
+```
+
+Then, Next.js will statically generate `/posts/1` and `/posts/2` during `next build` using the page component in `pages/posts/[id].js`.
+
+The value for each `params` object must match the parameters used in the page name:
+
+- If the page name is `pages/posts/[postId]/[commentId]`, then `params` should contain `postId` and `commentId`.
+- If the page name uses [catch-all routes](/docs/routing/dynamic-routes.md#catch-all-routes) like `pages/[...slug]`, then `params` should contain `slug` (which is an array). If this array is `['hello', 'world']`, then Next.js will statically generate the page at `/hello/world`.
+- If the page uses an [optional catch-all route](/docs/routing/dynamic-routes.md#optional-catch-all-routes), use `null`, `[]`, `undefined` or `false` to render the root-most route. For example, if you supply `slug: false` for `pages/[[...slug]]`, Next.js will statically generate the page `/`.
+
+The `params` strings are **case-sensitive** and ideally should be normalized to ensure the paths are generated correctly. For example, if `WoRLD` is returned for a param it will only match if `WoRLD` is the actual path visited, not `world` or `World`.
+
+Separate of the `params` object a `locale` field can be returned when [i18n is configured](/docs/advanced-features/i18n-routing.md), which configures the locale for the path being generated.
+
+### `fallback: false`
+
+If `fallback` is `false`, then any paths not returned by `getStaticPaths` will result in a **404 page**.
+
+When `next build` is run, Next.js will check if `getStaticPaths` returned `fallback: false`, it will then build **only** the paths returned by `getStaticPaths`. This option is useful if you have a small number of paths to create, or new page data is not added often. If you find that you need to add more paths, and you have `fallback: false`, you will need to run `next build` again so that the new paths can be generated.
+
+The following example pre-renders one blog post per page called `pages/posts/[id].js`. The list of blog posts will be fetched from a CMS and returned by `getStaticPaths`. Then, for each page, it fetches the post data from a CMS using [`getStaticProps`](/docs/api-reference/data-fetching/get-static-props.md).
+
+```jsx
+// pages/posts/[id].js
+
+function Post({ post }) {
+ // Render post...
+}
+
+// This function gets called at build time
+export async function getStaticPaths() {
+ // Call an external API endpoint to get posts
+ const res = await fetch('https://.../posts')
+ const posts = await res.json()
+
+ // Get the paths we want to pre-render based on posts
+ const paths = posts.map((post) => ({
+ params: { id: post.id },
+ }))
+
+ // We'll pre-render only these paths at build time.
+ // { fallback: false } means other routes should 404.
+ return { paths, fallback: false }
+}
+
+// This also gets called at build time
+export async function getStaticProps({ params }) {
+ // params contains the post `id`.
+ // If the route is like /posts/1, then params.id is 1
+ const res = await fetch(`https://.../posts/${params.id}`)
+ const post = await res.json()
+
+ // Pass post data to the page via props
+ return { props: { post } }
+}
+
+export default Post
+```
+
+### `fallback: true`
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://static-tweet.vercel.app">Static generation of a large number of pages</a></li>
+ </ul>
+</details>
+
+If `fallback` is `true`, then the behavior of `getStaticProps` changes in the following ways:
+
+- The paths returned from `getStaticPaths` will be rendered to `HTML` at build time by `getStaticProps`.
+- The paths that have not been generated at build time will **not** result in a 404 page. Instead, Next.js will serve a [“fallback”](#fallback-pages) version of the page on the first request to such a path. Web crawlers, such as Google, won't be served a fallback and instead the path will behave as in [`fallback: 'blocking'`](#fallback-blocking).
+- When a page with `fallback: true` is navigated to through `next/link` or `next/router` (client-side) Next.js will _not_ serve a fallback and instead the page will behave as [`fallback: 'blocking'`](#fallback-blocking).
+- In the background, Next.js will statically generate the requested path `HTML` and `JSON`. This includes running `getStaticProps`.
+- When complete, the browser receives the `JSON` for the generated path. This will be used to automatically render the page with the required props. From the user’s perspective, the page will be swapped from the fallback page to the full page.
+- At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time.
+
+> **Note:** `fallback: true` is not supported when using [`next export`](/docs/advanced-features/static-html-export.md).
+
+#### When is `fallback: true` useful?
+
+`fallback: true` is useful if your app has a very large number of static pages that depend on data (such as a very large e-commerce site). If you want to pre-render all product pages, the builds would take a very long time.
+
+Instead, you may statically generate a small subset of pages and use `fallback: true` for the rest. When someone requests a page that is not generated yet, the user will see the page with a loading indicator or skeleton component.
+
+Shortly after, `getStaticProps` finishes and the page will be rendered with the requested data. From now on, everyone who requests the same page will get the statically pre-rendered page.
+
+This ensures that users always have a fast experience while preserving fast builds and the benefits of Static Generation.
+
+`fallback: true` will not _update_ generated pages, for that take a look at [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md).
+
+### `fallback: 'blocking'`
+
+If `fallback` is `'blocking'`, new paths not returned by `getStaticPaths` will wait for the `HTML` to be generated, identical to SSR (hence why _blocking_), and then be cached for future requests so it only happens once per path.
+
+`getStaticProps` will behave as follows:
+
+- The paths returned from `getStaticPaths` will be rendered to `HTML` at build time by `getStaticProps`.
+- The paths that have not been generated at build time will **not** result in a 404 page. Instead, Next.js will SSR on the first request and return the generated `HTML`.
+- When complete, the browser receives the `HTML` for the generated path. From the user’s perspective, it will transition from "the browser is requesting the page" to "the full page is loaded". There is no flash of loading/fallback state.
+- At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time.
+
+`fallback: 'blocking'` will not _update_ generated pages by default. To update generated pages, use [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md) in conjunction with `fallback: 'blocking'`.
+
+> **Note:** `fallback: 'blocking'` is not supported when using [`next export`](/docs/advanced-features/static-html-export.md).
+
+### Fallback pages
+
+In the “fallback” version of a page:
+
+- The page’s props will be empty.
+- Using the [router](/docs/api-reference/next/router.md), you can detect if the fallback is being rendered, `router.isFallback` will be `true`.
+
+The following example showcases using `isFallback`:
+
+```jsx
+// pages/posts/[id].js
+import { useRouter } from 'next/router'
+
+function Post({ post }) {
+ const router = useRouter()
+
+ // If the page is not yet generated, this will be displayed
+ // initially until getStaticProps() finishes running
+ if (router.isFallback) {
+ return <div>Loading...</div>
+ }
+
+ // Render post...
+}
+
+// This function gets called at build time
+export async function getStaticPaths() {
+ return {
+ // Only `/posts/1` and `/posts/2` are generated at build time
+ paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
+ // Enable statically generating additional pages
+ // For example: `/posts/3`
+ fallback: true,
+ }
+}
+
+// This also gets called at build time
+export async function getStaticProps({ params }) {
+ // params contains the post `id`.
+ // If the route is like /posts/1, then params.id is 1
+ const res = await fetch(`https://.../posts/${params.id}`)
+ const post = await res.json()
+
+ // Pass post data to the page via props
+ return {
+ props: { post },
+ // Re-generate the post at most once per second
+ // if a request comes in
+ revalidate: 1,
+ }
+}
+
+export default Post
+```
+
+## getStaticPaths with TypeScript
+
+For TypeScript, you can use the `GetStaticPaths` type from `next`:
+
+```ts
+import { GetStaticPaths } from 'next'
+
+export const getStaticPaths: GetStaticPaths = async () => {
+ // ...
+}
+```
diff --git a/docs/api-reference/data-fetching/get-static-props.md b/docs/api-reference/data-fetching/get-static-props.md
new file mode 100644
index 0000000000000..4a1878780fc56
--- /dev/null
+++ b/docs/api-reference/data-fetching/get-static-props.md
@@ -0,0 +1,299 @@
+---
+description: API reference for `getStaticProps`. Learn how to use `getStaticProps` to generate static pages with Next.js.
+---
+
+# getStaticProps
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `v12.2.0` | [On-Demand Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md#on-demand-revalidation) is stable. |
+| `v12.1.0` | [On-Demand Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md#on-demand-revalidation) added (beta). |
+| `v10.0.0` | `locale`, `locales`, `defaultLocale`, and `notFound` options added. |
+| `v10.0.0` | `fallback: 'blocking'` return option added. |
+| `v9.5.0` | Stable [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md) |
+| `v9.3.0` | `getStaticProps` introduced. |
+
+</details>
+
+> **Note**: Next.js 13 introduces the `app/` directory (beta). This new directory has support for [colocated data fetching](https://beta.nextjs.org/docs/data-fetching/fundamentals) at the component level, using the new React `use` hook and an extended `fetch` Web API.
+>
+> [Learn more about incrementally adopting `app/`](https://beta.nextjs.org/docs/upgrade-guide).
+
+Exporting a function called `getStaticProps` will pre-render a page at build time using the props returned from the function:
+
+```jsx
+export async function getStaticProps(context) {
+ return {
+ props: {}, // will be passed to the page component as props
+ }
+}
+```
+
+You can import modules in top-level scope for use in `getStaticProps`. Imports used will **not be bundled for the client-side**. This means you can write **server-side code directly in `getStaticProps`**, including fetching data from your database.
+
+## Context parameter
+
+The `context` parameter is an object containing the following keys:
+
+- `params` contains the route parameters for pages using [dynamic routes](/docs/routing/dynamic-routes.md). 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` is `true` if the page is in the [Preview Mode](/docs/advanced-features/preview-mode.md) and `undefined` otherwise.
+- `previewData` contains the [preview](/docs/advanced-features/preview-mode.md) data set by `setPreviewData`.
+- `locale` contains the active locale (if enabled).
+- `locales` contains all supported locales (if enabled).
+- `defaultLocale` contains the configured default locale (if enabled).
+
+## getStaticProps return values
+
+The `getStaticProps` function should return an object containing either `props`, `redirect`, or `notFound` followed by an **optional** `revalidate` property.
+
+### `props`
+
+The `props` object is a key-value pair, where each value is received by the page component. It should be a [serializable object](https://developer.mozilla.org/en-US/docs/Glossary/Serialization) so that any props passed, could be serialized with [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
+
+```jsx
+export async function getStaticProps(context) {
+ return {
+ props: { message: `Next.js is awesome` }, // will be passed to the page component as props
+ }
+}
+```
+
+### `revalidate`
+
+The `revalidate` property is the amount in seconds after which a page re-generation can occur (defaults to `false` or no revalidation).
+
+```js
+// This function gets called at build time on server-side.
+// It may be called again, on a serverless function, if
+// revalidation is enabled and a new request comes in
+export async function getStaticProps() {
+ const res = await fetch('https://.../posts')
+ const posts = await res.json()
+
+ return {
+ props: {
+ posts,
+ },
+ // Next.js will attempt to re-generate the page:
+ // - When a request comes in
+ // - At most once every 10 seconds
+ revalidate: 10, // In seconds
+ }
+}
+```
+
+Learn more about [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md).
+
+The cache status of a page leveraging ISR can be determined by reading the value of the `x-nextjs-cache` response header. The possible values are the following:
+
+- `MISS` - the path is not in the cache (occurs at most once, on the first visit)
+- `STALE` - the path is in the cache but exceeded the revalidate time so it will be updated in the background
+- `HIT` - the path is in the cache and has not exceeded the revalidate time
+
+### `notFound`
+
+The `notFound` boolean allows the page to return a `404` status and [404 Page](/docs/advanced-features/custom-error-page.md#404-page). With `notFound: true`, the page will return a `404` even if there was a successfully generated page before. This is meant to support use cases like user-generated content getting removed by its author. Note, `notFound` follows the same `revalidate` behavior [described here](/docs/api-reference/data-fetching/get-static-props.md#revalidate).
+
+```js
+export async function getStaticProps(context) {
+ const res = await fetch(`https://.../data`)
+ const data = await res.json()
+
+ if (!data) {
+ return {
+ notFound: true,
+ }
+ }
+
+ return {
+ props: { data }, // will be passed to the page component as props
+ }
+}
+```
+
+> **Note**: `notFound` is not needed for [`fallback: false`](/docs/api-reference/data-fetching/get-static-paths#fallback-false) mode as only paths returned from `getStaticPaths` will be pre-rendered.
+
+### `redirect`
+
+The `redirect` object allows redirecting to internal or external resources. It should match the shape of `{ destination: string, permanent: boolean }`.
+
+In some rare cases, you might need to assign a custom status code for older `HTTP` clients to properly redirect. In these cases, you can use the `statusCode` property instead of the `permanent` property, **but not both**. You can also set `basePath: false` similar to redirects in `next.config.js`.
+
+```js
+export async function getStaticProps(context) {
+ const res = await fetch(`https://...`)
+ const data = await res.json()
+
+ if (!data) {
+ return {
+ redirect: {
+ destination: '/',
+ permanent: false,
+ // statusCode: 301
+ },
+ }
+ }
+
+ return {
+ props: { data }, // will be passed to the page component as props
+ }
+}
+```
+
+If the redirects are known at build-time, they should be added in [`next.config.js`](/docs/api-reference/next.config.js/redirects.md) instead.
+
+## Reading files: Use `process.cwd()`
+
+Files can be read directly from the filesystem in `getStaticProps`.
+
+In order to do so you have to get the full path to a file.
+
+Since Next.js compiles your code into a separate directory you can't use `__dirname` as the path it returns will be different from the pages directory.
+
+Instead you can use `process.cwd()` which gives you the directory where Next.js is being executed.
+
+```jsx
+import { promises as fs } from 'fs'
+import path from 'path'
+
+// posts will be populated at build time by getStaticProps()
+function Blog({ posts }) {
+ return (
+ <ul>
+ {posts.map((post) => (
+ <li>
+ <h3>{post.filename}</h3>
+ <p>{post.content}</p>
+ </li>
+ ))}
+ </ul>
+ )
+}
+
+// This function gets called at build time on server-side.
+// It won't be called on client-side, so you can even do
+// direct database queries.
+export async function getStaticProps() {
+ const postsDirectory = path.join(process.cwd(), 'posts')
+ const filenames = await fs.readdir(postsDirectory)
+
+ const posts = filenames.map(async (filename) => {
+ const filePath = path.join(postsDirectory, filename)
+ const fileContents = await fs.readFile(filePath, 'utf8')
+
+ // Generally you would parse/transform the contents
+ // For example you can transform markdown to HTML here
+
+ return {
+ filename,
+ content: fileContents,
+ }
+ })
+ // By returning { props: { posts } }, the Blog component
+ // will receive `posts` as a prop at build time
+ return {
+ props: {
+ posts: await Promise.all(posts),
+ },
+ }
+}
+
+export default Blog
+```
+
+## getStaticProps with TypeScript
+
+The type of `getStaticProps` can be specified using `GetStaticProps` from `next`:
+
+```ts
+import { GetStaticProps } from 'next'
+
+type Post = {
+ author: string
+ content: string
+}
+
+export const getStaticProps: GetStaticProps<{ posts: Post[] }> = async (
+ context
+) => {
+ const res = await fetch('https://.../posts')
+ const posts: Post[] = await res.json()
+
+ return {
+ props: {
+ posts,
+ },
+ }
+}
+```
+
+If you want to get inferred typings for your props, you can use `InferGetStaticPropsType<typeof getStaticProps>`:
+
+```tsx
+import { InferGetStaticPropsType } from 'next'
+import { GetStaticProps } from 'next'
+
+type Post = {
+ author: string
+ content: string
+}
+
+export const getStaticProps: GetStaticProps<{ posts: Post[] }> = async () => {
+ const res = await fetch('https://.../posts')
+ const posts: Post[] = await res.json()
+
+ return {
+ props: {
+ posts,
+ },
+ }
+}
+
+function Blog({ posts }: InferGetStaticPropsType<typeof getStaticProps>) {
+ // will resolve posts to type Post[]
+}
+
+export default Blog
+```
+
+Implicit typing for `getStaticProps` will also work properly:
+
+```tsx
+import { InferGetStaticPropsType } from 'next'
+
+type Post = {
+ author: string
+ content: string
+}
+
+export const getStaticProps = async () => {
+ const res = await fetch('https://.../posts')
+ const posts: Post[] = await res.json()
+
+ return {
+ props: {
+ posts,
+ },
+ }
+}
+
+function Blog({ posts }: InferGetStaticPropsType<typeof getStaticProps>) {
+ // will resolve posts to type Post[]
+}
+
+export default Blog
+```
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/basic-features/data-fetching/overview.md">
+ <b>Data Fetching:</b>
+ <small>Learn more about data fetching in Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/edge-runtime.md b/docs/api-reference/edge-runtime.md
new file mode 100644
index 0000000000000..3471b5c041672
--- /dev/null
+++ b/docs/api-reference/edge-runtime.md
@@ -0,0 +1,180 @@
+---
+description: The Next.js Edge Runtime is based on standard Web APIs. Learn more about the supported APIs available.
+---
+
+# Edge Runtime
+
+The Next.js Edge Runtime is based on standard Web APIs, which is used by [Middleware](/docs/middleware.md) and [Edge API Routes](/docs/api-routes/edge-api-routes.md).
+
+## Network APIs
+
+- [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
+- [`Fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+- [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent)
+- [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+- [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+- [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+- [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+- [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
+- [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File)
+- [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
+
+## Encoding APIs
+
+- [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
+- [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)
+- [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/atob)
+- [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/btoa)
+
+## Web Stream APIs
+
+- [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
+- [`ReadableStreamBYOBReader`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader)
+- [`ReadableStreamDefaultReader`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader)
+- [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream)
+- [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream)
+- [`WritableStreamDefaultWriter`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter)
+
+## Web Crypto APIs
+
+- [`crypto`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)
+- [`CryptoKey`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey)
+- [`SubtleCrypto`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)
+
+## Web Standards APIs
+
+- [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)
+- [`URLPattern`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern)
+- [`Web Cache`](https://developer.mozilla.org/en-US/docs/Web/API/Cache)
+
+## V8 Primitives
+
+- [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+- [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
+- [`Atomics`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Atomics)
+- [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
+- [`BigInt64Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array)
+- [`BigUint64Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array)
+- [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
+- [`clearInterval`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/clearInterval)
+- [`clearTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/clearTimeout)
+- [`console`](https://developer.mozilla.org/en-US/docs/Web/API/Console)
+- [`DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView)
+- [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
+- [`decodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI)
+- [`decodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent)
+- [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)
+- [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
+- [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
+- [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError)
+- [`Float32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array)
+- [`Float64Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array)
+- [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
+- [`Infinity`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity)
+- [`Int8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int8Array)
+- [`Int16Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int16Array)
+- [`Int32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int32Array)
+- [`Intl`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
+- [`isFinite`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isFinite)
+- [`isNaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isNaN)
+- [`JSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)
+- [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
+- [`Math`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math)
+- [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)
+- [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+- [`parseFloat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat)
+- [`parseInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt)
+- [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+- [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
+- [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError)
+- [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError)
+- [`Reflect`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect)
+- [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)
+- [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)
+- [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setInterval)
+- [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setTimeout)
+- [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer)
+- [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)
+- [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol)
+- [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError)
+- [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
+- [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)
+- [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError)
+- [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
+- [`Uint8ClampedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8ClampedArray)
+- [`Uint16Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint16Array)
+- [`Uint32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint32Array)
+- [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)
+- [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
+- [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+- [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)
+- [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet)
+- [`WebAssembly`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly)
+
+## Environment Variables
+
+You can use `process.env` to access [Environment Variables](/docs/basic-features/environment-variables.md) for both `next dev` and `next build`.
+
+Running `console.log` on `process.env` **will not** show all your Environment Variables. You have to access the variables directly as shown below:
+
+```javascript
+console.log(process.env)
+// { NEXT_RUNTIME: 'edge' }
+console.log(process.env.TEST_VARIABLE)
+// value
+```
+
+## Unsupported APIs
+
+The Edge Runtime has some restrictions including:
+
+- Native Node.js APIs **are not supported**. For example, you can't read or write to the filesystem
+- `node_modules` _can_ be used, as long as they implement ES Modules and do not use native Node.js APIs
+- Calling `require` directly is **not allowed**. Use ES Modules instead
+
+The following JavaScript language features are disabled, and **will not work:**
+
+- `eval`: Evaluates JavaScript code represented as a string
+- `new Function(evalString)`: Creates a new function with the code provided as an argument
+- `WebAssembly.compile`
+- `WebAssembly.instantiate` with [a buffer parameter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate#primary_overload_%E2%80%94_taking_wasm_binary_code)
+
+In rare cases, your code could contain (or import) some dynamic code evaluation statements which _can not be reached at runtime_ and which can not be removed by treeshaking.
+You can relax the check to allow specific files with your Middleware or Edge API Route exported configuration:
+
+```javascript
+export const config = {
+ runtime: 'experimental-edge', // for Edge API Routes only
+ unstable_allowDynamic: [
+ '/lib/utilities.js', // allows a single file
+ '/node_modules/function-bind/**', // use a glob to allow anything in the function-bind 3rd party module
+ ],
+}
+```
+
+`unstable_allowDynamic` is a [glob](https://github.com/micromatch/micromatch#matching-features), or an array of globs, ignoring dynamic code evaluation for specific files. The globs are relative to your application root folder.
+
+Be warned that if these statements are executed on the Edge, _they will throw and cause a runtime error_.
+
+## Related
+
+<div class="card">
+ <a href="/docs/advanced-features/middleware.md">
+ <b>Middleware</b>
+ <small>Run code before a request is completed.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-reference/next/server.md">
+ <b>Middleware API Reference</b>
+ <small>Learn more about the supported APIs for Middleware.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-routes/edge-api-routes.md">
+ <b>Edge API Routes</b>
+ <small>Build high performance APIs in Next.js. </small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/basepath.md b/docs/api-reference/next.config.js/basepath.md
new file mode 100644
index 0000000000000..696120ba4c662
--- /dev/null
+++ b/docs/api-reference/next.config.js/basepath.md
@@ -0,0 +1,77 @@
+---
+description: Learn more about setting a base path in Next.js
+---
+
+# Base Path
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| -------- | ---------------- |
+| `v9.5.0` | Base Path added. |
+
+</details>
+
+To deploy a Next.js application under a sub-path of a domain you can use the `basePath` config option.
+
+`basePath` allows you to set a path prefix for the application. For example, to use `/docs` instead of `/` (the default), open `next.config.js` and add the `basePath` config:
+
+```js
+module.exports = {
+ basePath: '/docs',
+}
+```
+
+Note: this value must be set at build time and can not be changed without re-building as the value is inlined in the client-side bundles.
+
+## Links
+
+When linking to other pages using `next/link` and `next/router` the `basePath` will be automatically applied.
+
+For example, using `/about` will automatically become `/docs/about` when `basePath` is set to `/docs`.
+
+```js
+export default function HomePage() {
+ return (
+ <>
+ <Link href="/about">About Page</Link>
+ </>
+ )
+}
+```
+
+Output html:
+
+```html
+<a href="/docs/about">About Page</a>
+```
+
+This makes sure that you don't have to change all links in your application when changing the `basePath` value.
+
+## Images
+
+When using the [`next/image`](/docs/api-reference/next/image.md) component, you will need to add the `basePath` in front of `src`.
+
+For example, using `/docs/me.png` will properly serve your image when `basePath` is set to `/docs`.
+
+```jsx
+import Image from 'next/image'
+
+function Home() {
+ return (
+ <>
+ <h1>My Homepage</h1>
+ <Image
+ src="/docs/me.png"
+ alt="Picture of the author"
+ width={500}
+ height={500}
+ />
+ <p>Welcome to my homepage!</p>
+ </>
+ )
+}
+
+export default Home
+```
diff --git a/docs/api-reference/next.config.js/build-indicator.md b/docs/api-reference/next.config.js/build-indicator.md
new file mode 100644
index 0000000000000..cccaa3d4bfad6
--- /dev/null
+++ b/docs/api-reference/next.config.js/build-indicator.md
@@ -0,0 +1,29 @@
+---
+description: In development mode, pages include an indicator to let you know if your new code it's being compiled. You can opt-out of it here.
+---
+
+# Build indicator
+
+When you edit your code, and Next.js is compiling the application, a compilation indicator appears in the bottom right corner of the page.
+
+> **Note:** This indicator is only present in development mode and will not appear when building and running the app in production mode.
+
+In some cases this indicator can be misplaced on your page, for example, when conflicting with a chat launcher. To change its position, open `next.config.js` and set the `buildActivityPosition` in the `devIndicators` object to `bottom-right` (default), `bottom-left`, `top-right` or `top-left`:
+
+```js
+module.exports = {
+ devIndicators: {
+ buildActivityPosition: 'bottom-right',
+ },
+}
+```
+
+In some cases this indicator might not be useful for you. To remove it, open `next.config.js` and disable the `buildActivity` config in `devIndicators` object:
+
+```js
+module.exports = {
+ devIndicators: {
+ buildActivity: false,
+ },
+}
+```
diff --git a/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md b/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md
new file mode 100644
index 0000000000000..a69b3a7abfc24
--- /dev/null
+++ b/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md
@@ -0,0 +1,61 @@
+---
+description: A custom asset prefix allows you serve static assets from a CDN. Learn more about it here.
+---
+
+# CDN Support with Asset Prefix
+
+> **Attention**: [Deploying to Vercel](/docs/deployment.md) automatically configures a global CDN for your Next.js project.
+> You do not need to manually setup an Asset Prefix.
+
+> **Note**: Next.js 9.5+ added support for a customizable [Base Path](/docs/api-reference/next.config.js/basepath.md), which is better
+> suited for hosting your application on a sub-path like `/docs`.
+> We do not suggest you use a custom Asset Prefix for this use case.
+
+To set up a [CDN](https://en.wikipedia.org/wiki/Content_delivery_network), you can set up an asset prefix and configure your CDN's origin to resolve to the domain that Next.js is hosted on.
+
+Open `next.config.js` and add the `assetPrefix` config:
+
+```js
+const isProd = process.env.NODE_ENV === 'production'
+
+module.exports = {
+ // Use the CDN in production and localhost for development.
+ assetPrefix: isProd ? 'https://cdn.mydomain.com' : undefined,
+}
+```
+
+Next.js will automatically use your asset prefix for the JavaScript and CSS files it loads from the `/_next/` path (`.next/static/` folder). For example, with the above configuration, the following request for a JS chunk:
+
+```
+/_next/static/chunks/4b9b41aaa062cbbfeff4add70f256968c51ece5d.4d708494b3aed70c04f0.js
+```
+
+Would instead become:
+
+```
+https://cdn.mydomain.com/_next/static/chunks/4b9b41aaa062cbbfeff4add70f256968c51ece5d.4d708494b3aed70c04f0.js
+```
+
+The exact configuration for uploading your files to a given CDN will depend on your CDN of choice. The only folder you need to host on your CDN is the contents of `.next/static/`, which should be uploaded as `_next/static/` as the above URL request indicates. **Do not upload the rest of your `.next/` folder**, as you should not expose your server code and other configuration to the public.
+
+While `assetPrefix` covers requests to `_next/static`, it does not influence the following paths:
+
+- Files in the [public](/docs/basic-features/static-file-serving.md) folder; if you want to serve those assets over a CDN, you'll have to introduce the prefix yourself
+- `/_next/data/` requests for `getServerSideProps` pages. These requests will always be made against the main domain since they're not static.
+- `/_next/data/` requests for `getStaticProps` pages. These requests will always be made against the main domain to support [Incremental Static Generation](/docs/basic-features/data-fetching/incremental-static-regeneration.md), even if you're not using it (for consistency).
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/basic-features/static-file-serving.md">
+ <b>Static File Serving:</b>
+ <small>Serve static files, like images, in the public directory.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/compression.md b/docs/api-reference/next.config.js/compression.md
new file mode 100644
index 0000000000000..6947040d2ec01
--- /dev/null
+++ b/docs/api-reference/next.config.js/compression.md
@@ -0,0 +1,24 @@
+---
+description: Next.js provides gzip compression to compress rendered content and static files, it only works with the server target. Learn more about it here.
+---
+
+# Compression
+
+Next.js provides [**gzip**](https://tools.ietf.org/html/rfc6713#section-3) compression to compress rendered content and static files. In general you will want to enable compression on a HTTP proxy like [nginx](https://www.nginx.com/), to offload load from the `Node.js` process.
+
+To disable **compression**, open `next.config.js` and disable the `compress` config:
+
+```js
+module.exports = {
+ compress: false,
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/configuring-onDemandEntries.md b/docs/api-reference/next.config.js/configuring-onDemandEntries.md
new file mode 100644
index 0000000000000..2e9133a9d2d0b
--- /dev/null
+++ b/docs/api-reference/next.config.js/configuring-onDemandEntries.md
@@ -0,0 +1,29 @@
+---
+description: Configure how Next.js will dispose and keep in memory pages created in development.
+---
+
+# Configuring onDemandEntries
+
+Next.js exposes some options that give you some control over how the server will dispose or keep in memory built pages in development.
+
+To change the defaults, open `next.config.js` and add the `onDemandEntries` config:
+
+```js
+module.exports = {
+ onDemandEntries: {
+ // period (in ms) where the server will keep pages in the buffer
+ maxInactiveAge: 25 * 1000,
+ // number of pages that should be kept simultaneously without being disposed
+ pagesBufferLength: 2,
+ },
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/configuring-the-build-id.md b/docs/api-reference/next.config.js/configuring-the-build-id.md
new file mode 100644
index 0000000000000..aba9bd2cc8adf
--- /dev/null
+++ b/docs/api-reference/next.config.js/configuring-the-build-id.md
@@ -0,0 +1,27 @@
+---
+description: Configure the build id, which is used to identify the current build in which your application is being served.
+---
+
+# Configuring the Build ID
+
+Next.js uses a constant id generated at build time to identify which version of your application is being served. This can cause problems in multi-server deployments when `next build` is run on every server. In order to keep a consistent build id between builds you can provide your own build id.
+
+Open `next.config.js` and add the `generateBuildId` function:
+
+```js
+module.exports = {
+ generateBuildId: async () => {
+ // You can, for example, get the latest git commit hash here
+ return 'my-build-id'
+ },
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/custom-page-extensions.md b/docs/api-reference/next.config.js/custom-page-extensions.md
new file mode 100644
index 0000000000000..8d191afb010bd
--- /dev/null
+++ b/docs/api-reference/next.config.js/custom-page-extensions.md
@@ -0,0 +1,43 @@
+---
+description: Extend the default page extensions used by Next.js when resolving pages in the pages directory.
+---
+
+# Custom Page Extensions
+
+You can extend the default Page extensions (`.tsx`, `.ts`, `.jsx`, `.js`) used by Next.js. Inside `next.config.js`, add the `pageExtensions` config:
+
+```js
+module.exports = {
+ pageExtensions: ['mdx', 'md', 'jsx', 'js', 'tsx', 'ts'],
+}
+```
+
+Changing these values affects _all_ Next.js pages, including the following:
+
+- `middleware.js`
+- `pages/_document.js`
+- `pages/_app.js`
+- `pages/api/`
+
+For example, if you reconfigure `.ts` page extensions to `.page.ts`, you would need to rename pages like `_app.page.ts`.
+
+## Including non-page files in the `pages` directory
+
+You can colocate test files or other files used by components in the `pages` directory. Inside `next.config.js`, add the `pageExtensions` config:
+
+```js
+module.exports = {
+ pageExtensions: ['page.tsx', 'page.ts', 'page.jsx', 'page.js'],
+}
+```
+
+Then, rename your pages to have a file extension that includes `.page` (e.g. rename `MyPage.tsx` to `MyPage.page.tsx`). Ensure you rename _all_ Next.js pages, including the files mentioned above.
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/custom-webpack-config.md b/docs/api-reference/next.config.js/custom-webpack-config.md
new file mode 100644
index 0000000000000..b26aae2403772
--- /dev/null
+++ b/docs/api-reference/next.config.js/custom-webpack-config.md
@@ -0,0 +1,83 @@
+---
+description: Extend the default webpack config added by Next.js.
+---
+
+# Custom Webpack Config
+
+> Note: changes to webpack config are not covered by semver so proceed at your own risk
+
+Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case:
+
+- [CSS imports](/docs/basic-features/built-in-css-support.md#adding-a-global-stylesheet)
+- [CSS modules](/docs/basic-features/built-in-css-support.md#adding-component-level-css)
+- [Sass/SCSS imports](/docs/basic-features/built-in-css-support.md#sass-support)
+- [Sass/SCSS modules](/docs/basic-features/built-in-css-support.md#sass-support)
+- [preact](https://github.com/vercel/next.js/tree/canary/examples/using-preact)
+- [Customizing babel configuration](/docs/advanced-features/customizing-babel-config.md)
+
+Some commonly asked for features are available as plugins:
+
+- [@next/mdx](https://github.com/vercel/next.js/tree/canary/packages/next-mdx)
+- [@next/bundle-analyzer](https://github.com/vercel/next.js/tree/canary/packages/next-bundle-analyzer)
+
+In order to extend our usage of `webpack`, you can define a function that extends its config inside `next.config.js`, like so:
+
+```js
+module.exports = {
+ webpack: (
+ config,
+ { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack }
+ ) => {
+ // Important: return the modified config
+ return config
+ },
+}
+```
+
+> The `webpack` function is executed twice, once for the server and once for the client. This allows you to distinguish between client and server configuration using the `isServer` property.
+
+The second argument to the `webpack` function is an object with the following properties:
+
+- `buildId`: `String` - The build id, used as a unique identifier between builds
+- `dev`: `Boolean` - Indicates if the compilation will be done in development
+- `isServer`: `Boolean` - It's `true` for server-side compilation, and `false` for client-side compilation
+- `nextRuntime`: `String | undefined` - The target runtime for server-side compilation; either `"edge"` or `"nodejs"`, it's `undefined` for client-side compilation.
+- `defaultLoaders`: `Object` - Default loaders used internally by Next.js:
+ - `babel`: `Object` - Default `babel-loader` configuration
+
+Example usage of `defaultLoaders.babel`:
+
+```js
+// Example config for adding a loader that depends on babel-loader
+// This source was taken from the @next/mdx plugin source:
+// https://github.com/vercel/next.js/tree/canary/packages/next-mdx
+module.exports = {
+ webpack: (config, options) => {
+ config.module.rules.push({
+ test: /\.mdx/,
+ use: [
+ options.defaultLoaders.babel,
+ {
+ loader: '@mdx-js/loader',
+ options: pluginOptions.options,
+ },
+ ],
+ })
+
+ return config
+ },
+}
+```
+
+#### `nextRuntime`
+
+Notice that `isServer` is `true` when `nextRuntime` is `"edge"` or `"nodejs"`, nextRuntime "`edge`" is currently for middleware and server components in edge runtime only.
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/disabling-etag-generation.md b/docs/api-reference/next.config.js/disabling-etag-generation.md
new file mode 100644
index 0000000000000..71a2f82cf5fff
--- /dev/null
+++ b/docs/api-reference/next.config.js/disabling-etag-generation.md
@@ -0,0 +1,24 @@
+---
+description: Next.js will generate etags for every page by default. Learn more about how to disable etag generation here.
+---
+
+# Disabling ETag Generation
+
+Next.js will generate [etags](https://en.wikipedia.org/wiki/HTTP_ETag) for every page by default. You may want to disable etag generation for HTML pages depending on your cache strategy.
+
+Open `next.config.js` and disable the `generateEtags` option:
+
+```js
+module.exports = {
+ generateEtags: false,
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/disabling-http-keep-alive.md b/docs/api-reference/next.config.js/disabling-http-keep-alive.md
new file mode 100644
index 0000000000000..bfa79ad3d8b6d
--- /dev/null
+++ b/docs/api-reference/next.config.js/disabling-http-keep-alive.md
@@ -0,0 +1,36 @@
+---
+description: Next.js will automatically use HTTP Keep-Alive by default. Learn more about how to disable HTTP Keep-Alive here.
+---
+
+# Disabling HTTP Keep-Alive
+
+Next.js automatically polyfills [node-fetch](/docs/basic-features/supported-browsers-features#polyfills) and enables [HTTP Keep-Alive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive) by default. You may want to disable HTTP Keep-Alive for certain `fetch()` calls or globally.
+
+For a single `fetch()` call, you can add the agent option:
+
+```js
+import { Agent } from 'https'
+
+const url = 'https://example.com'
+const agent = new Agent({ keepAlive: false })
+fetch(url, { agent })
+```
+
+To override all `fetch()` calls globally, you can use `next.config.js`:
+
+```js
+module.exports = {
+ httpAgentOptions: {
+ keepAlive: false,
+ },
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/disabling-x-powered-by.md b/docs/api-reference/next.config.js/disabling-x-powered-by.md
new file mode 100644
index 0000000000000..29a0810f08eed
--- /dev/null
+++ b/docs/api-reference/next.config.js/disabling-x-powered-by.md
@@ -0,0 +1,22 @@
+---
+description: Next.js will add the `x-powered-by` header by default. Learn to opt-out of it here.
+---
+
+# Disabling x-powered-by
+
+By default Next.js will add the `x-powered-by` header. To opt-out of it, open `next.config.js` and disable the `poweredByHeader` config:
+
+```js
+module.exports = {
+ poweredByHeader: false,
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/environment-variables.md b/docs/api-reference/next.config.js/environment-variables.md
new file mode 100644
index 0000000000000..c3732a640080f
--- /dev/null
+++ b/docs/api-reference/next.config.js/environment-variables.md
@@ -0,0 +1,66 @@
+---
+description: Learn to add and access environment variables in your Next.js application at build time.
+---
+
+# Environment Variables
+
+> 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/basic-features/environment-variables.md). Give it a try!
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-env-from-next-config-js">With env</a></li>
+ </ul>
+</details>
+
+> <b>Note</b>: environment variables specified in this way will <b>always</b> 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/basic-features/environment-variables.md).
+
+To add environment variables to the JavaScript bundle, open `next.config.js` and add the `env` config:
+
+```js
+module.exports = {
+ env: {
+ customKey: 'my-value',
+ },
+}
+```
+
+Now you can access `process.env.customKey` in your code. For example:
+
+```jsx
+function Page() {
+ return <h1>The value of customKey is: {process.env.customKey}</h1>
+}
+
+export default Page
+```
+
+Next.js will replace `process.env.customKey` with `'my-value'` at build time. Trying to destructure `process.env` variables won't work due to the nature of webpack [DefinePlugin](https://webpack.js.org/plugins/define-plugin/).
+
+For example, the following line:
+
+```jsx
+return <h1>The value of customKey is: {process.env.customKey}</h1>
+```
+
+Will end up being:
+
+```jsx
+return <h1>The value of customKey is: {'my-value'}</h1>
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/basic-features/environment-variables.md">
+ <b>Built-in support for Environment Variables:</b>
+ <small>Learn more about the new support for environment variables.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/exportPathMap.md b/docs/api-reference/next.config.js/exportPathMap.md
new file mode 100644
index 0000000000000..4180363e6dcfd
--- /dev/null
+++ b/docs/api-reference/next.config.js/exportPathMap.md
@@ -0,0 +1,98 @@
+---
+description: Customize the pages that will be exported as HTML files when using `next export`.
+---
+
+# exportPathMap
+
+> This feature is exclusive to `next export`. Please refer to [Static HTML export](/docs/advanced-features/static-html-export.md) if you want to learn more about it.
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-static-export">Static Export</a></li>
+ </ul>
+</details>
+
+`exportPathMap` allows you to specify a mapping of request paths to page destinations, to be used during export. Paths defined in `exportPathMap` will also be available when using [`next dev`](/docs/api-reference/cli.md#development).
+
+Let's start with an example, to create a custom `exportPathMap` for an app with the following pages:
+
+- `pages/index.js`
+- `pages/about.js`
+- `pages/post.js`
+
+Open `next.config.js` and add the following `exportPathMap` config:
+
+```js
+module.exports = {
+ exportPathMap: async function (
+ defaultPathMap,
+ { dev, dir, outDir, distDir, buildId }
+ ) {
+ return {
+ '/': { page: '/' },
+ '/about': { page: '/about' },
+ '/p/hello-nextjs': { page: '/post', query: { title: 'hello-nextjs' } },
+ '/p/learn-nextjs': { page: '/post', query: { title: 'learn-nextjs' } },
+ '/p/deploy-nextjs': { page: '/post', query: { title: 'deploy-nextjs' } },
+ }
+ },
+}
+```
+
+> Note: the `query` field in `exportPathMap` cannot be used with [automatically statically optimized pages](/docs/advanced-features/automatic-static-optimization) or [`getStaticProps` pages](/docs/basic-features/data-fetching/get-static-props.md) as they are rendered to HTML files at build-time and additional query information cannot be provided during `next export`.
+
+The pages will then be exported as HTML files, for example, `/about` will become `/about.html`.
+
+`exportPathMap` is an `async` function that receives 2 arguments: the first one is `defaultPathMap`, which is the default map used by Next.js. The second argument is an object with:
+
+- `dev` - `true` when `exportPathMap` is being called in development. `false` when running `next export`. In development `exportPathMap` is used to define routes.
+- `dir` - Absolute path to the project directory
+- `outDir` - Absolute path to the `out/` directory ([configurable with `-o`](#customizing-the-output-directory)). When `dev` is `true` the value of `outDir` will be `null`.
+- `distDir` - Absolute path to the `.next/` directory (configurable with the [`distDir`](/docs/api-reference/next.config.js/setting-a-custom-build-directory.md) config)
+- `buildId` - The generated build id
+
+The returned object is a map of pages where the `key` is the `pathname` and the `value` is an object that accepts the following fields:
+
+- `page`: `String` - the page inside the `pages` directory to render
+- `query`: `Object` - the `query` object passed to `getInitialProps` when prerendering. Defaults to `{}`
+
+> The exported `pathname` can also be a filename (for example, `/readme.md`), but you may need to set the `Content-Type` header to `text/html` when serving its content if it is different than `.html`.
+
+## Adding a trailing slash
+
+It is possible to configure Next.js to export pages as `index.html` files and require trailing slashes, `/about` becomes `/about/index.html` and is routable via `/about/`. This was the default behavior prior to Next.js 9.
+
+To switch back and add a trailing slash, open `next.config.js` and enable the `trailingSlash` config:
+
+```js
+module.exports = {
+ trailingSlash: true,
+}
+```
+
+## Customizing the output directory
+
+[`next export`](/docs/advanced-features/static-html-export.md#how-to-use-it) will use `out` as the default output directory, you can customize this using the `-o` argument, like so:
+
+```bash
+next export -o outdir
+```
+
+> **Warning**: Using `exportPathMap` for defining routes with any `getStaticPaths` powered page is now ignored and gets overridden. We recommend not to use them together.
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/advanced-features/static-html-export.md">
+ <b>Static HTML Export:</b>
+ <small>Export your Next.js app to static HTML.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/headers.md b/docs/api-reference/next.config.js/headers.md
new file mode 100644
index 0000000000000..3fb5be5578a33
--- /dev/null
+++ b/docs/api-reference/next.config.js/headers.md
@@ -0,0 +1,403 @@
+---
+description: Add custom HTTP headers to your Next.js app.
+---
+
+# Headers
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/headers">Headers</a></li>
+ </ul>
+</details>
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | -------------- |
+| `v10.2.0` | `has` added. |
+| `v9.5.0` | Headers added. |
+
+</details>
+
+Headers allow you to set custom HTTP headers on the response to an incoming request on a given path.
+
+To set custom HTTP headers you can use the `headers` key in `next.config.js`:
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/about',
+ headers: [
+ {
+ key: 'x-custom-header',
+ value: 'my custom header value',
+ },
+ {
+ key: 'x-another-custom-header',
+ value: 'my other custom header value',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+`headers` is an async function that expects an array to be returned holding objects with `source` and `headers` properties:
+
+- `source` is the incoming request path pattern.
+- `headers` is an array of response header objects, with `key` and `value` properties.
+- `basePath`: `false` or `undefined` - if false the basePath won't be included when matching, can be used for external rewrites only.
+- `locale`: `false` or `undefined` - whether the locale should not be included when matching.
+- `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
+
+Headers are checked before the filesystem which includes pages and `/public` files.
+
+## Header Overriding Behavior
+
+If two headers match the same path and set the same header key, the last header key will override the first. Using the below headers, the path `/hello` will result in the header `x-hello` being `world` due to the last header value set being `world`.
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/:path*',
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'there',
+ },
+ ],
+ },
+ {
+ source: '/hello',
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+## Path Matching
+
+Path matches are allowed, for example `/blog/:slug` will match `/blog/hello-world` (no nested paths):
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/blog/:slug',
+ headers: [
+ {
+ key: 'x-slug',
+ value: ':slug', // Matched parameters can be used in the value
+ },
+ {
+ key: 'x-slug-:slug', // Matched parameters can be used in the key
+ value: 'my other custom header value',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+### Wildcard Path Matching
+
+To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/blog/:slug*',
+ headers: [
+ {
+ key: 'x-slug',
+ value: ':slug*', // Matched parameters can be used in the value
+ },
+ {
+ key: 'x-slug-:slug*', // Matched parameters can be used in the key
+ value: 'my other custom header value',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+### Regex Path Matching
+
+To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`:
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ source: '/blog/:post(\\d{1,})',
+ headers: [
+ {
+ key: 'x-post',
+ value: ':post',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+The following characters `(`, `)`, `{`, `}`, `:`, `*`, `+`, `?` are used for regex path matching, so when used in the `source` as non-special values they must be escaped by adding `\\` before them:
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ {
+ // this will match `/english(default)/something` being requested
+ source: '/english\\(default\\)/:slug',
+ headers: [
+ {
+ key: 'x-header',
+ value: 'value',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+## Header, Cookie, and Query Matching
+
+To only apply a header when either header, cookie, or query values also match the `has` field can be used. Both the `source` and all `has` items must match for the header to be applied.
+
+`has` items have the following fields:
+
+- `type`: `String` - must be either `header`, `cookie`, `host`, or `query`.
+- `key`: `String` - the key from the selected type to match against.
+- `value`: `String` or `undefined` - the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value `first-(?<paramName>.*)` is used for `first-second` then `second` will be usable in the destination with `:paramName`.
+
+```js
+module.exports = {
+ async headers() {
+ return [
+ // if the header `x-add-header` is present,
+ // the `x-another-header` header will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'header',
+ key: 'x-add-header',
+ },
+ ],
+ headers: [
+ {
+ key: 'x-another-header',
+ value: 'hello',
+ },
+ ],
+ },
+ // if the source, query, and cookie are matched,
+ // the `x-authorized` header will be applied
+ {
+ source: '/specific/:path*',
+ has: [
+ {
+ type: 'query',
+ key: 'page',
+ // the page value will not be available in the
+ // header key/values since value is provided and
+ // doesn't use a named capture group e.g. (?<page>home)
+ value: 'home',
+ },
+ {
+ type: 'cookie',
+ key: 'authorized',
+ value: 'true',
+ },
+ ],
+ headers: [
+ {
+ key: 'x-authorized',
+ value: ':authorized',
+ },
+ ],
+ },
+ // if the header `x-authorized` is present and
+ // contains a matching value, the `x-another-header` will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'header',
+ key: 'x-authorized',
+ value: '(?<authorized>yes|true)',
+ },
+ ],
+ headers: [
+ {
+ key: 'x-another-header',
+ value: ':authorized',
+ },
+ ],
+ },
+ // if the host is `example.com`,
+ // this header will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'host',
+ value: 'example.com',
+ },
+ ],
+ headers: [
+ {
+ key: 'x-another-header',
+ value: ':authorized',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+### Headers with basePath support
+
+When leveraging [`basePath` support](/docs/api-reference/next.config.js/basepath.md) with headers each `source` is automatically prefixed with the `basePath` unless you add `basePath: false` to the header:
+
+```js
+module.exports = {
+ basePath: '/docs',
+
+ async headers() {
+ return [
+ {
+ source: '/with-basePath', // becomes /docs/with-basePath
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ {
+ source: '/without-basePath', // is not modified since basePath: false is set
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ basePath: false,
+ },
+ ]
+ },
+}
+```
+
+### Headers with i18n support
+
+When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with headers each `source` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the header. If `locale: false` is used you must prefix the `source` with a locale for it to be matched correctly.
+
+```js
+module.exports = {
+ i18n: {
+ locales: ['en', 'fr', 'de'],
+ defaultLocale: 'en',
+ },
+
+ async headers() {
+ return [
+ {
+ source: '/with-locale', // automatically handles all locales
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ {
+ // does not handle locales automatically since locale: false is set
+ source: '/nl/with-locale-manual',
+ locale: false,
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ {
+ // this matches '/' since `en` is the defaultLocale
+ source: '/en',
+ locale: false,
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ {
+ // this gets converted to /(en|fr|de)/(.*) so will not match the top-level
+ // `/` or `/fr` routes like /:path* would
+ source: '/(.*)',
+ headers: [
+ {
+ key: 'x-hello',
+ value: 'world',
+ },
+ ],
+ },
+ ]
+ },
+}
+```
+
+### Cache-Control
+
+You can set the `Cache-Control` header in your [Next.js API Routes](/docs/api-routes/introduction.md) by using the `res.setHeader` method:
+
+```js
+// pages/api/user.js
+
+export default function handler(req, res) {
+ res.setHeader('Cache-Control', 's-maxage=86400')
+ res.status(200).json({ name: 'John Doe' })
+}
+```
+
+You cannot set `Cache-Control` headers in `next.config.js` file as these will be overwritten in production to ensure that API Routes and static assets are cached effectively.
+
+If you need to revalidate the cache of a page that has been [statically generated](/docs/basic-features/pages.md#static-generation-recommended), you can do so by setting the `revalidate` prop in the page's [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) function.
+
+## Related
+
+For more information, we recommend the following sections:
+
+<div class="card">
+ <a href="/docs/advanced-features/security-headers.md">
+ <b>Security Headers:</b>
+ <small>Improve the security of your Next.js application by add HTTP response headers.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/ignoring-eslint.md b/docs/api-reference/next.config.js/ignoring-eslint.md
new file mode 100644
index 0000000000000..650c678bfd072
--- /dev/null
+++ b/docs/api-reference/next.config.js/ignoring-eslint.md
@@ -0,0 +1,37 @@
+---
+description: Next.js reports ESLint errors and warnings during builds by default. Learn how to opt-out of this behavior here.
+---
+
+# Ignoring ESLint
+
+When ESLint is detected in your project, Next.js fails your **production build** (`next build`) when errors are present.
+
+If you'd like Next.js to produce production code even when your application has ESLint errors, you can disable the built-in linting step completely. This is not recommended unless you already have ESLint configured to run in a separate part of your workflow (for example, in CI or a pre-commit hook).
+
+Open `next.config.js` and enable the `ignoreDuringBuilds` option in the `eslint` config:
+
+```js
+module.exports = {
+ eslint: {
+ // Warning: This allows production builds to successfully complete even if
+ // your project has ESLint errors.
+ ignoreDuringBuilds: true,
+ },
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/basic-features/eslint.md">
+ <b>ESLint:</b>
+ <small>Get started with ESLint in Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/ignoring-typescript-errors.md b/docs/api-reference/next.config.js/ignoring-typescript-errors.md
new file mode 100644
index 0000000000000..a26cbc26cbc8f
--- /dev/null
+++ b/docs/api-reference/next.config.js/ignoring-typescript-errors.md
@@ -0,0 +1,41 @@
+---
+description: Next.js reports TypeScript errors by default. Learn to opt-out of this behavior here.
+---
+
+# Ignoring TypeScript Errors
+
+Next.js fails your **production build** (`next build`) when TypeScript errors are present in your project.
+
+If you'd like Next.js to dangerously produce production code even when your application has errors, you can disable the built-in type checking step.
+
+If disabled, be sure you are running type checks as part of your build or deploy process, otherwise this can be very dangerous.
+
+Open `next.config.js` and enable the `ignoreBuildErrors` option in the `typescript` config:
+
+```js
+module.exports = {
+ typescript: {
+ // !! WARN !!
+ // Dangerously allow production builds to successfully complete even if
+ // your project has type errors.
+ // !! WARN !!
+ ignoreBuildErrors: true,
+ },
+}
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/basic-features/typescript.md">
+ <b>TypeScript:</b>
+ <small>Get started with TypeScript in Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/introduction.md b/docs/api-reference/next.config.js/introduction.md
new file mode 100644
index 0000000000000..732b4a32320fe
--- /dev/null
+++ b/docs/api-reference/next.config.js/introduction.md
@@ -0,0 +1,87 @@
+---
+description: learn more about the configuration file used by Next.js to handle your application.
+---
+
+# next.config.js
+
+For custom advanced configuration of Next.js, you can create a `next.config.js` or `next.config.mjs` file in the root of your project directory (next to `package.json`).
+
+`next.config.js` is a regular Node.js module, not a JSON file. It gets used by the Next.js server and build phases, and it's not included in the browser build.
+
+Take a look at the following `next.config.js` example:
+
+```js
+/**
+ * @type {import('next').NextConfig}
+ */
+const nextConfig = {
+ /* config options here */
+}
+
+module.exports = nextConfig
+```
+
+If you need [ECMAScript modules](https://nodejs.org/api/esm.html), you can use `next.config.mjs`:
+
+```js
+/**
+ * @type {import('next').NextConfig}
+ */
+const nextConfig = {
+ /* config options here */
+}
+
+export default nextConfig
+```
+
+You can also use a function:
+
+```js
+module.exports = (phase, { defaultConfig }) => {
+ /**
+ * @type {import('next').NextConfig}
+ */
+ const nextConfig = {
+ /* config options here */
+ }
+ return nextConfig
+}
+```
+
+Since Next.js 12.1.0, you can use an async function:
+
+```js
+module.exports = async (phase, { defaultConfig }) => {
+ /**
+ * @type {import('next').NextConfig}
+ */
+ const nextConfig = {
+ /* config options here */
+ }
+ return nextConfig
+}
+```
+
+`phase` is the current context in which the configuration is loaded. You can see the [available phases](https://github.com/vercel/next.js/blob/5e6b008b561caf2710ab7be63320a3d549474a5b/packages/next/shared/lib/constants.ts#L19-L23). Phases can be imported from `next/constants`:
+
+```js
+const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')
+
+module.exports = (phase, { defaultConfig }) => {
+ if (phase === PHASE_DEVELOPMENT_SERVER) {
+ return {
+ /* development only config options here */
+ }
+ }
+
+ return {
+ /* config options for all phases except development here */
+ }
+}
+```
+
+The commented lines are the place where you can put the configs allowed by `next.config.js`, which are [defined in this file](https://github.com/vercel/next.js/blob/canary/packages/next/server/config-shared.ts#L158).
+
+However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do.
+
+> Avoid using new JavaScript features not available in your target Node.js version. `next.config.js` will not be parsed by Webpack, Babel or TypeScript.
diff --git a/docs/api-reference/next.config.js/react-strict-mode.md b/docs/api-reference/next.config.js/react-strict-mode.md
new file mode 100644
index 0000000000000..b844bf84506fd
--- /dev/null
+++ b/docs/api-reference/next.config.js/react-strict-mode.md
@@ -0,0 +1,29 @@
+---
+description: The complete Next.js runtime is now Strict Mode-compliant, learn how to opt-in
+---
+
+# React Strict Mode
+
+> **Suggested**: We strongly suggest you enable Strict Mode in your Next.js application to better prepare your application for the future of React.
+
+React's [Strict Mode](https://reactjs.org/docs/strict-mode.html) is a development mode only feature for highlighting potential problems in an application. It helps to identify unsafe lifecycles, legacy API usage, and a number of other features.
+
+The Next.js runtime is Strict Mode-compliant. To opt-in to Strict Mode, configure the following option in your `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+ reactStrictMode: true,
+}
+```
+
+If you or your team are not ready to use Strict Mode in your entire application, that's OK! You can incrementally migrate on a page-by-page basis using `<React.StrictMode>`.
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/redirects.md b/docs/api-reference/next.config.js/redirects.md
new file mode 100644
index 0000000000000..ddd1c5baca7c4
--- /dev/null
+++ b/docs/api-reference/next.config.js/redirects.md
@@ -0,0 +1,305 @@
+---
+description: Add redirects to your Next.js app.
+---
+
+# Redirects
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/redirects">Redirects</a></li>
+ </ul>
+</details>
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | ---------------- |
+| `v10.2.0` | `has` added. |
+| `v9.5.0` | Redirects added. |
+
+</details>
+
+Redirects allow you to redirect an incoming request path to a different destination path.
+
+To use Redirects you can use the `redirects` key in `next.config.js`:
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ source: '/about',
+ destination: '/',
+ permanent: true,
+ },
+ ]
+ },
+}
+```
+
+`redirects` is an async function that expects an array to be returned holding objects with `source`, `destination`, and `permanent` properties:
+
+- `source` is the incoming request path pattern.
+- `destination` is the path you want to route to.
+- `permanent` `true` or `false` - if `true` will use the 308 status code which instructs clients/search engines to cache the redirect forever, if `false` will use the 307 status code which is temporary and is not cached.
+
+> **Why does Next.js use 307 and 308?** Traditionally a 302 was used for a temporary redirect, and a 301 for a permanent redirect, but many browsers changed the request method of the redirect to `GET`, regardless of the original method. For example, if the browser made a request to `POST /v1/users` which returned status code `302` with location `/v2/users`, the subsequent request might be `GET /v2/users` instead of the expected `POST /v2/users`. Next.js uses the 307 temporary redirect, and 308 permanent redirect status codes to explicitly preserve the request method used.
+
+- `basePath`: `false` or `undefined` - if false the `basePath` won't be included when matching, can be used for external redirects only.
+- `locale`: `false` or `undefined` - whether the locale should not be included when matching.
+- `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
+
+Redirects are checked before the filesystem which includes pages and `/public` files.
+
+Redirects are not applied to client-side routing (`Link`, `router.push`), unless [Middleware](/docs/advanced-features/middleware) is present and matches the path.
+
+When a redirect is applied, any query values provided in the request will be passed through to the redirect destination. For example, see the following redirect configuration:
+
+```js
+{
+ source: '/old-blog/:path*',
+ destination: '/blog/:path*',
+ permanent: false
+}
+```
+
+When `/old-blog/post-1?hello=world` is requested, the client will be redirected to `/blog/post-1?hello=world`.
+
+## Path Matching
+
+Path matches are allowed, for example `/old-blog/:slug` will match `/old-blog/hello-world` (no nested paths):
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ source: '/old-blog/:slug',
+ destination: '/news/:slug', // Matched parameters can be used in the destination
+ permanent: true,
+ },
+ ]
+ },
+}
+```
+
+### Wildcard Path Matching
+
+To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ source: '/blog/:slug*',
+ destination: '/news/:slug*', // Matched parameters can be used in the destination
+ permanent: true,
+ },
+ ]
+ },
+}
+```
+
+### Regex Path Matching
+
+To match a regex path you can wrap the regex in parentheses after a parameter, for example `/post/:slug(\\d{1,})` will match `/post/123` but not `/post/abc`:
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ source: '/post/:slug(\\d{1,})',
+ destination: '/news/:slug', // Matched parameters can be used in the destination
+ permanent: false,
+ },
+ ]
+ },
+}
+```
+
+The following characters `(`, `)`, `{`, `}`, `:`, `*`, `+`, `?` are used for regex path matching, so when used in the `source` as non-special values they must be escaped by adding `\\` before them:
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ {
+ // this will match `/english(default)/something` being requested
+ source: '/english\\(default\\)/:slug',
+ destination: '/en-us/:slug',
+ permanent: false,
+ },
+ ]
+ },
+}
+```
+
+## Header, Cookie, and Query Matching
+
+To only match a redirect when header, cookie, or query values also match the `has` field can be used. Both the `source` and all `has` items must match for the redirect to be applied.
+
+`has` items have the following fields:
+
+- `type`: `String` - must be either `header`, `cookie`, `host`, or `query`.
+- `key`: `String` - the key from the selected type to match against.
+- `value`: `String` or `undefined` - the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value `first-(?<paramName>.*)` is used for `first-second` then `second` will be usable in the destination with `:paramName`.
+
+```js
+module.exports = {
+ async redirects() {
+ return [
+ // if the header `x-redirect-me` is present,
+ // this redirect will be applied
+ {
+ source: '/:path((?!another-page$).*)',
+ has: [
+ {
+ type: 'header',
+ key: 'x-redirect-me',
+ },
+ ],
+ permanent: false,
+ destination: '/another-page',
+ },
+ // if the source, query, and cookie are matched,
+ // this redirect will be applied
+ {
+ source: '/specific/:path*',
+ has: [
+ {
+ type: 'query',
+ key: 'page',
+ // the page value will not be available in the
+ // destination since value is provided and doesn't
+ // use a named capture group e.g. (?<page>home)
+ value: 'home',
+ },
+ {
+ type: 'cookie',
+ key: 'authorized',
+ value: 'true',
+ },
+ ],
+ permanent: false,
+ destination: '/another/:path*',
+ },
+ // if the header `x-authorized` is present and
+ // contains a matching value, this redirect will be applied
+ {
+ source: '/',
+ has: [
+ {
+ type: 'header',
+ key: 'x-authorized',
+ value: '(?<authorized>yes|true)',
+ },
+ ],
+ permanent: false,
+ destination: '/home?authorized=:authorized',
+ },
+ // if the host is `example.com`,
+ // this redirect will be applied
+ {
+ source: '/:path((?!another-page$).*)',
+ has: [
+ {
+ type: 'host',
+ value: 'example.com',
+ },
+ ],
+ permanent: false,
+ destination: '/another-page',
+ },
+ ]
+ },
+}
+```
+
+### Redirects with basePath support
+
+When leveraging [`basePath` support](/docs/api-reference/next.config.js/basepath.md) with redirects each `source` and `destination` is automatically prefixed with the `basePath` unless you add `basePath: false` to the redirect:
+
+```js
+module.exports = {
+ basePath: '/docs',
+
+ async redirects() {
+ return [
+ {
+ source: '/with-basePath', // automatically becomes /docs/with-basePath
+ destination: '/another', // automatically becomes /docs/another
+ permanent: false,
+ },
+ {
+ // does not add /docs since basePath: false is set
+ source: '/without-basePath',
+ destination: '/another',
+ basePath: false,
+ permanent: false,
+ },
+ ]
+ },
+}
+```
+
+### Redirects with i18n support
+
+When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with redirects each `source` and `destination` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the redirect. If `locale: false` is used you must prefix the `source` and `destination` with a locale for it to be matched correctly.
+
+```js
+module.exports = {
+ i18n: {
+ locales: ['en', 'fr', 'de'],
+ defaultLocale: 'en',
+ },
+
+ async redirects() {
+ return [
+ {
+ source: '/with-locale', // automatically handles all locales
+ destination: '/another', // automatically passes the locale on
+ permanent: false,
+ },
+ {
+ // does not handle locales automatically since locale: false is set
+ source: '/nl/with-locale-manual',
+ destination: '/nl/another',
+ locale: false,
+ permanent: false,
+ },
+ {
+ // this matches '/' since `en` is the defaultLocale
+ source: '/en',
+ destination: '/en/another',
+ locale: false,
+ permanent: false,
+ },
+ // it's possible to match all locales even when locale: false is set
+ {
+ source: '/:locale/page',
+ destination: '/en/newpage',
+ permanent: false,
+ locale: false,
+ }
+ {
+ // this gets converted to /(en|fr|de)/(.*) so will not match the top-level
+ // `/` or `/fr` routes like /:path* would
+ source: '/(.*)',
+ destination: '/another',
+ permanent: false,
+ },
+ ]
+ },
+}
+```
+
+In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the `statusCode` property instead of the `permanent` property, but not both. Note: to ensure IE11 compatibility a `Refresh` header is automatically added for the 308 status code.
+
+## Other Redirects
+
+- Inside [API Routes](/docs/api-routes/response-helpers.md), you can use `res.redirect()`.
+- Inside [`getStaticProps`](/docs/api-reference/data-fetching/get-static-props.md) and [`getServerSideProps`](/docs/api-reference/data-fetching/get-server-side-props.md), you can redirect specific pages at request-time.
diff --git a/docs/api-reference/next.config.js/rewrites.md b/docs/api-reference/next.config.js/rewrites.md
new file mode 100644
index 0000000000000..d83621a7ca8f0
--- /dev/null
+++ b/docs/api-reference/next.config.js/rewrites.md
@@ -0,0 +1,439 @@
+---
+description: Add rewrites to your Next.js app.
+---
+
+# Rewrites
+
+<details open>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/rewrites">Rewrites</a></li>
+ </ul>
+</details>
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | --------------- |
+| `v10.2.0` | `has` added. |
+| `v9.5.0` | Rewrites added. |
+
+</details>
+
+Rewrites allow you to map an incoming request path to a different destination path.
+
+Rewrites act as a URL proxy and mask the destination path, making it appear the user hasn't changed their location on the site. In contrast, [redirects](/docs/api-reference/next.config.js/redirects.md) will reroute to a new page and show the URL changes.
+
+To use rewrites you can use the `rewrites` key in `next.config.js`:
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/about',
+ destination: '/',
+ },
+ ]
+ },
+}
+```
+
+Rewrites are applied to client-side routing, a `<Link href="/about">` will have the rewrite applied in the above example.
+
+`rewrites` is an async function that expects to return either an array or an object of arrays (see below) holding objects with `source` and `destination` properties:
+
+- `source`: `String` - is the incoming request path pattern.
+- `destination`: `String` is the path you want to route to.
+- `basePath`: `false` or `undefined` - if false the basePath won't be included when matching, can be used for external rewrites only.
+- `locale`: `false` or `undefined` - whether the locale should not be included when matching.
+- `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
+
+When the `rewrites` function returns an array, rewrites are applied after checking the filesystem (pages and `/public` files) and before dynamic routes. When the `rewrites` function returns an object of arrays with a specific shape, this behavior can be changed and more finely controlled, as of `v10.1` of Next.js:
+
+```js
+module.exports = {
+ async rewrites() {
+ return {
+ beforeFiles: [
+ // These rewrites are checked after headers/redirects
+ // and before all files including _next/public files which
+ // allows overriding page files
+ {
+ source: '/some-page',
+ destination: '/somewhere-else',
+ has: [{ type: 'query', key: 'overrideMe' }],
+ },
+ ],
+ afterFiles: [
+ // These rewrites are checked after pages/public files
+ // are checked but before dynamic routes
+ {
+ source: '/non-existent',
+ destination: '/somewhere-else',
+ },
+ ],
+ fallback: [
+ // These rewrites are checked after both pages/public files
+ // and dynamic routes are checked
+ {
+ source: '/:path*',
+ destination: `https://my-old-site.com/:path*`,
+ },
+ ],
+ }
+ },
+}
+```
+
+Note: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked.
+
+The order Next.js routes are checked is:
+
+1. [headers](/docs/api-reference/next.config.js/headers) are checked/applied
+2. [redirects](/docs/api-reference/next.config.js/redirects) are checked/applied
+3. `beforeFiles` rewrites are checked/applied
+4. static files from the [public directory](/docs/basic-features/static-file-serving), `_next/static` files, and non-dynamic pages are checked/served
+5. `afterFiles` rewrites are checked/applied, if one of these rewrites is matched we check dynamic routes/static files after each match
+6. `fallback` rewrites are checked/applied, these are applied before rendering the 404 page and after dynamic routes/all static assets have been checked. If you use [fallback: true/'blocking'](/docs/api-reference/data-fetching/get-static-paths#fallback-true) in `getStaticPaths`, the fallback `rewrites` defined in your `next.config.js` will _not_ be run.
+
+## Rewrite parameters
+
+When using parameters in a rewrite the parameters will be passed in the query by default when none of the parameters are used in the `destination`.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/old-about/:path*',
+ destination: '/about', // The :path parameter isn't used here so will be automatically passed in the query
+ },
+ ]
+ },
+}
+```
+
+If a parameter is used in the destination none of the parameters will be automatically passed in the query.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/docs/:path*',
+ destination: '/:path*', // The :path parameter is used here so will not be automatically passed in the query
+ },
+ ]
+ },
+}
+```
+
+You can still pass the parameters manually in the query if one is already used in the destination by specifying the query in the `destination`.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/:first/:second',
+ destination: '/:first?second=:second',
+ // Since the :first parameter is used in the destination the :second parameter
+ // will not automatically be added in the query although we can manually add it
+ // as shown above
+ },
+ ]
+ },
+}
+```
+
+Note: for static pages from the [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) or [prerendering](/docs/basic-features/data-fetching/get-static-props.md) params from rewrites will be parsed on the client after hydration and provided in the query.
+
+## Path Matching
+
+Path matches are allowed, for example `/blog/:slug` will match `/blog/hello-world` (no nested paths):
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/blog/:slug',
+ destination: '/news/:slug', // Matched parameters can be used in the destination
+ },
+ ]
+ },
+}
+```
+
+### Wildcard Path Matching
+
+To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/blog/:slug*',
+ destination: '/news/:slug*', // Matched parameters can be used in the destination
+ },
+ ]
+ },
+}
+```
+
+### Regex Path Matching
+
+To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`:
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/old-blog/:post(\\d{1,})',
+ destination: '/blog/:post', // Matched parameters can be used in the destination
+ },
+ ]
+ },
+}
+```
+
+The following characters `(`, `)`, `{`, `}`, `:`, `*`, `+`, `?` are used for regex path matching, so when used in the `source` as non-special values they must be escaped by adding `\\` before them:
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ // this will match `/english(default)/something` being requested
+ source: '/english\\(default\\)/:slug',
+ destination: '/en-us/:slug',
+ },
+ ]
+ },
+}
+```
+
+## Header, Cookie, and Query Matching
+
+To only match a rewrite when header, cookie, or query values also match the `has` field can be used. Both the `source` and all `has` items must match for the rewrite to be applied.
+
+`has` items have the following fields:
+
+- `type`: `String` - must be either `header`, `cookie`, `host`, or `query`.
+- `key`: `String` - the key from the selected type to match against.
+- `value`: `String` or `undefined` - the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value `first-(?<paramName>.*)` is used for `first-second` then `second` will be usable in the destination with `:paramName`.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ // if the header `x-rewrite-me` is present,
+ // this rewrite will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'header',
+ key: 'x-rewrite-me',
+ },
+ ],
+ destination: '/another-page',
+ },
+ // if the source, query, and cookie are matched,
+ // this rewrite will be applied
+ {
+ source: '/specific/:path*',
+ has: [
+ {
+ type: 'query',
+ key: 'page',
+ // the page value will not be available in the
+ // destination since value is provided and doesn't
+ // use a named capture group e.g. (?<page>home)
+ value: 'home',
+ },
+ {
+ type: 'cookie',
+ key: 'authorized',
+ value: 'true',
+ },
+ ],
+ destination: '/:path*/home',
+ },
+ // if the header `x-authorized` is present and
+ // contains a matching value, this rewrite will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'header',
+ key: 'x-authorized',
+ value: '(?<authorized>yes|true)',
+ },
+ ],
+ destination: '/home?authorized=:authorized',
+ },
+ // if the host is `example.com`,
+ // this rewrite will be applied
+ {
+ source: '/:path*',
+ has: [
+ {
+ type: 'host',
+ value: 'example.com',
+ },
+ ],
+ destination: '/another-page',
+ },
+ ]
+ },
+}
+```
+
+## Rewriting to an external URL
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/custom-routes-proxying">Incremental adoption of Next.js</a></li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-zones">Using Multiple Zones</a></li>
+ </ul>
+</details>
+
+Rewrites allow you to rewrite to an external url. This is especially useful for incrementally adopting Next.js. The following is an example rewrite for redirecting the `/blog` route of your main app to an external site.
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/blog',
+ destination: 'https://example.com/blog',
+ },
+ {
+ source: '/blog/:slug',
+ destination: 'https://example.com/blog/:slug', // Matched parameters can be used in the destination
+ },
+ ]
+ },
+}
+```
+
+If you're using `trailingSlash: true`, you also need to insert a trailing slash in the `source` parameter. If the destination server is also expecting a trailing slash it should be included in the `destination` parameter as well.
+
+```js
+module.exports = {
+ trailingSlash: true,
+ async rewrites() {
+ return [
+ {
+ source: '/blog/',
+ destination: 'https://example.com/blog/',
+ },
+ {
+ source: '/blog/:path*/',
+ destination: 'https://example.com/blog/:path*/',
+ },
+ ]
+ },
+}
+```
+
+### Incremental adoption of Next.js
+
+You can also have Next.js fall back to proxying to an existing website after checking all Next.js routes.
+
+This way you don't have to change the rewrites configuration when migrating more pages to Next.js
+
+```js
+module.exports = {
+ async rewrites() {
+ return {
+ fallback: [
+ {
+ source: '/:path*',
+ destination: `https://custom-routes-proxying-endpoint.vercel.app/:path*`,
+ },
+ ],
+ }
+ },
+}
+```
+
+See additional information on incremental adoption [in the docs here](/docs/migrating/incremental-adoption.md).
+
+### Rewrites with basePath support
+
+When leveraging [`basePath` support](/docs/api-reference/next.config.js/basepath.md) with rewrites each `source` and `destination` is automatically prefixed with the `basePath` unless you add `basePath: false` to the rewrite:
+
+```js
+module.exports = {
+ basePath: '/docs',
+
+ async rewrites() {
+ return [
+ {
+ source: '/with-basePath', // automatically becomes /docs/with-basePath
+ destination: '/another', // automatically becomes /docs/another
+ },
+ {
+ // does not add /docs to /without-basePath since basePath: false is set
+ // Note: this can not be used for internal rewrites e.g. `destination: '/another'`
+ source: '/without-basePath',
+ destination: 'https://example.com',
+ basePath: false,
+ },
+ ]
+ },
+}
+```
+
+### Rewrites with i18n support
+
+When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with rewrites each `source` and `destination` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the rewrite. If `locale: false` is used you must prefix the `source` and `destination` with a locale for it to be matched correctly.
+
+```js
+module.exports = {
+ i18n: {
+ locales: ['en', 'fr', 'de'],
+ defaultLocale: 'en',
+ },
+
+ async rewrites() {
+ return [
+ {
+ source: '/with-locale', // automatically handles all locales
+ destination: '/another', // automatically passes the locale on
+ },
+ {
+ // does not handle locales automatically since locale: false is set
+ source: '/nl/with-locale-manual',
+ destination: '/nl/another',
+ locale: false,
+ },
+ {
+ // this matches '/' since `en` is the defaultLocale
+ source: '/en',
+ destination: '/en/another',
+ locale: false,
+ },
+ {
+ // it's possible to match all locales even when locale: false is set
+ source: '/:locale/api-alias/:path*',
+ destination: '/api/:path*',
+ locale: false,
+ },
+ {
+ // this gets converted to /(en|fr|de)/(.*) so will not match the top-level
+ // `/` or `/fr` routes like /:path* would
+ source: '/(.*)',
+ destination: '/another',
+ },
+ ]
+ },
+}
+```
diff --git a/docs/api-reference/next.config.js/runtime-configuration.md b/docs/api-reference/next.config.js/runtime-configuration.md
new file mode 100644
index 0000000000000..94dd42551534b
--- /dev/null
+++ b/docs/api-reference/next.config.js/runtime-configuration.md
@@ -0,0 +1,73 @@
+---
+description: Add client and server runtime configuration to your Next.js app.
+---
+
+# Runtime Configuration
+
+> Generally you'll want to use [build-time environment variables](/docs/basic-features/environment-variables.md) to provide your configuration. The reason for this is that runtime configuration adds rendering / initialization overhead and is incompatible with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
+
+To add runtime configuration to your app open `next.config.js` and add the `publicRuntimeConfig` and `serverRuntimeConfig` configs:
+
+```js
+module.exports = {
+ serverRuntimeConfig: {
+ // Will only be available on the server side
+ mySecret: 'secret',
+ secondSecret: process.env.SECOND_SECRET, // Pass through env variables
+ },
+ publicRuntimeConfig: {
+ // Will be available on both server and client
+ staticFolder: '/static',
+ },
+}
+```
+
+Place any server-only runtime config under `serverRuntimeConfig`.
+
+Anything accessible to both client and server-side code should be under `publicRuntimeConfig`.
+
+> A page that relies on `publicRuntimeConfig` **must** use `getInitialProps` or `getServerSideProps` or your application must have a [Custom App](/docs/advanced-features/custom-app.md) with `getInitialProps` to opt-out of [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md). Runtime configuration won't be available to any page (or component in a page) without being server-side rendered.
+
+To get access to the runtime configs in your app use `next/config`, like so:
+
+```jsx
+import getConfig from 'next/config'
+import Image from 'next/image'
+
+// Only holds serverRuntimeConfig and publicRuntimeConfig
+const { serverRuntimeConfig, publicRuntimeConfig } = getConfig()
+// Will only be available on the server-side
+console.log(serverRuntimeConfig.mySecret)
+// Will be available on both server-side and client-side
+console.log(publicRuntimeConfig.staticFolder)
+
+function MyImage() {
+ return (
+ <div>
+ <Image
+ src={`${publicRuntimeConfig.staticFolder}/logo.png`}
+ alt="logo"
+ layout="fill"
+ />
+ </div>
+ )
+}
+
+export default MyImage
+```
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/environment-variables.md">
+ <b>Environment Variables:</b>
+ <small>Access environment variables in your Next.js application at build time.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/setting-a-custom-build-directory.md b/docs/api-reference/next.config.js/setting-a-custom-build-directory.md
new file mode 100644
index 0000000000000..47e269bfa9e6d
--- /dev/null
+++ b/docs/api-reference/next.config.js/setting-a-custom-build-directory.md
@@ -0,0 +1,28 @@
+---
+description: Set a custom build directory to use instead of the default .next directory.
+---
+
+# Setting a custom build directory
+
+You can specify a name to use for a custom build directory to use instead of `.next`.
+
+Open `next.config.js` and add the `distDir` config:
+
+```js
+module.exports = {
+ distDir: 'build',
+}
+```
+
+Now if you run `next build` Next.js will use `build` instead of the default `.next` folder.
+
+> `distDir` **should not** leave your project directory. For example, `../build` is an **invalid** directory.
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/static-optimization-indicator.md b/docs/api-reference/next.config.js/static-optimization-indicator.md
new file mode 100644
index 0000000000000..f8c512d388a44
--- /dev/null
+++ b/docs/api-reference/next.config.js/static-optimization-indicator.md
@@ -0,0 +1,21 @@
+---
+description: Optimized pages include an indicator to let you know if it's being statically optimized. You can opt-out of it here.
+---
+
+# Static Optimization Indicator
+
+> **Note:** This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js.
+
+When a page qualifies for [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) we show an indicator to let you know.
+
+This is helpful since automatic static optimization can be very beneficial and knowing immediately in development if the page qualifies can be useful.
+
+In some cases this indicator might not be useful, like when working on electron applications. To remove it open `next.config.js` and disable the `autoPrerender` config in `devIndicators`:
+
+```js
+module.exports = {
+ devIndicators: {
+ autoPrerender: false,
+ },
+}
+```
diff --git a/docs/api-reference/next.config.js/trailing-slash.md b/docs/api-reference/next.config.js/trailing-slash.md
new file mode 100644
index 0000000000000..ee2757f872ccc
--- /dev/null
+++ b/docs/api-reference/next.config.js/trailing-slash.md
@@ -0,0 +1,35 @@
+---
+description: Configure Next.js pages to resolve with or without a trailing slash.
+---
+
+# Trailing Slash
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| -------- | --------------------- |
+| `v9.5.0` | Trailing Slash added. |
+
+</details>
+
+By default Next.js will redirect urls with trailing slashes to their counterpart without a trailing slash. For example `/about/` will redirect to `/about`. You can configure this behavior to act the opposite way, where urls without trailing slashes are redirected to their counterparts with trailing slashes.
+
+Open `next.config.js` and add the `trailingSlash` config:
+
+```js
+module.exports = {
+ trailingSlash: true,
+}
+```
+
+With this option set, urls like `/about` will redirect to `/about/`.
+
+## Related
+
+<div class="card">
+ <a href="/docs/api-reference/next.config.js/introduction.md">
+ <b>Introduction to next.config.js:</b>
+ <small>Learn more about the configuration file used by Next.js.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next.config.js/url-imports.md b/docs/api-reference/next.config.js/url-imports.md
new file mode 100644
index 0000000000000..1473c7dd571b1
--- /dev/null
+++ b/docs/api-reference/next.config.js/url-imports.md
@@ -0,0 +1,94 @@
+---
+description: Configure Next.js to allow importing modules from external URLs (experimental).
+---
+
+# URL Imports
+
+URL imports are an experimental feature that allows you to import modules directly from external servers (instead of from the local disk).
+
+> **Warning**: This feature is experimental. Only use domains that you trust to download and execute on your machine. Please exercise
+> discretion, and caution until the feature is flagged as stable.
+
+To opt-in, add the allowed URL prefixes inside `next.config.js`:
+
+```js
+module.exports = {
+ experimental: {
+ urlImports: ['https://example.com/modules/'],
+ },
+}
+```
+
+Then, you can import modules directly from URLs:
+
+```js
+import { a, b, c } from 'https://example.com/modules/some/module.js'
+```
+
+URL Imports can be used everywhere normal package imports can be used.
+
+## Security Model
+
+This feature is being designed with **security as the top priority**. To start, we added an experimental flag forcing you to explicitly allow the domains you accept URL imports from. We're working to take this further by limiting URL imports to execute in the browser sandbox using the [Edge Runtime](/docs/api-reference/edge-runtime.md).
+
+## Lockfile
+
+When using URL imports, Next.js will create a lockfile in the `next.lock` directory.
+This directory is intended to be committed to Git and should **not be included** in your `.gitignore` file.
+
+- When running `next dev`, Next.js will download and add all newly discovered URL Imports to your lockfile
+- When running `next build`, Next.js will use only the lockfile to build the application for production
+
+Typically, no network requests are needed and any outdated lockfile will cause the build to fail.
+One exception is resources that respond with `Cache-Control: no-cache`.
+These resources will have a `no-cache` entry in the lockfile and will always be fetched from the network on each build.
+
+## Examples
+
+### Skypack
+
+```js
+import confetti from 'https://cdn.skypack.dev/canvas-confetti'
+import { useEffect } from 'react'
+
+export default () => {
+ useEffect(() => {
+ confetti()
+ })
+ return <p>Hello</p>
+}
+```
+
+### Static Image Imports
+
+```js
+import Image from 'next/image'
+import logo from 'https://github.com/vercel/next.js/raw/canary/test/integration/production/public/vercel.png'
+
+export default () => (
+ <div>
+ <Image src={logo} placeholder="blur" />
+ </div>
+)
+```
+
+### URLs in CSS
+
+```css
+.className {
+ background: url('https://github.com/vercel/next.js/raw/canary/test/integration/production/public/vercel.png');
+}
+```
+
+### Asset Imports
+
+```js
+import Image from 'next/image'
+
+const logo = new URL(
+ 'https://github.com/vercel/next.js/raw/canary/test/integration/production/public/vercel.png',
+ import.meta.url
+)
+
+export default () => <div>{logo.pathname}</div>
+```
diff --git a/docs/api-reference/next/amp.md b/docs/api-reference/next/amp.md
new file mode 100644
index 0000000000000..6cc212791168d
--- /dev/null
+++ b/docs/api-reference/next/amp.md
@@ -0,0 +1,87 @@
+---
+description: Enable AMP in a page, and control the way Next.js adds AMP to the page with the AMP config.
+---
+
+# next/amp
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/amp">AMP</a></li>
+ </ul>
+</details>
+
+> AMP support is one of our advanced features, you can [read more about AMP here](/docs/advanced-features/amp-support/introduction.md).
+
+To enable AMP, add the following config to your page:
+
+```jsx
+export const config = { amp: true }
+```
+
+The `amp` config accepts the following values:
+
+- `true` - The page will be AMP-only
+- `'hybrid'` - The page will have two versions, one with AMP and another one with HTML
+
+To learn more about the `amp` config, read the sections below.
+
+## AMP First Page
+
+Take a look at the following example:
+
+```jsx
+export const config = { amp: true }
+
+function About(props) {
+ return <h3>My AMP About Page!</h3>
+}
+
+export default About
+```
+
+The page above is an AMP-only page, which means:
+
+- The page has no Next.js or React client-side runtime
+- The page is automatically optimized with [AMP Optimizer](https://github.com/ampproject/amp-toolbox/tree/master/packages/optimizer), an optimizer that applies the same transformations as AMP caches (improves performance by up to 42%)
+- The page has a user-accessible (optimized) version of the page and a search-engine indexable (unoptimized) version of the page
+
+## Hybrid AMP Page
+
+Take a look at the following example:
+
+```jsx
+import { useAmp } from 'next/amp'
+
+export const config = { amp: 'hybrid' }
+
+function About(props) {
+ const isAmp = useAmp()
+
+ return (
+ <div>
+ <h3>My AMP About Page!</h3>
+ {isAmp ? (
+ <amp-img
+ width="300"
+ height="300"
+ src="/my-img.jpg"
+ alt="a cool image"
+ layout="responsive"
+ />
+ ) : (
+ <img width="300" height="300" src="/my-img.jpg" alt="a cool image" />
+ )}
+ </div>
+ )
+}
+
+export default About
+```
+
+The page above is a hybrid AMP page, which means:
+
+- The page is rendered as traditional HTML (default) and AMP HTML (by adding `?amp=1` to the URL)
+- The AMP version of the page only has valid optimizations applied with AMP Optimizer so that it is indexable by search-engines
+
+The page uses `useAmp` to differentiate between modes, it's a [React Hook](https://reactjs.org/docs/hooks-intro.html) that returns `true` if the page is using AMP, and `false` otherwise.
diff --git a/docs/api-reference/next/font.md b/docs/api-reference/next/font.md
new file mode 100644
index 0000000000000..77cb2caa28aa8
--- /dev/null
+++ b/docs/api-reference/next/font.md
@@ -0,0 +1,316 @@
+---
+description: Optimizing loading web fonts with the built-in `@next/font` loaders.
+---
+
+# @next/font
+
+<details>
+ <summary><b>Version History</b></summary>
+
+| Version | Changes |
+| --------- | ----------------------- |
+| `v13.0.0` | `@next/font` was added. |
+
+</details>
+
+This API reference will help you understand how to use `@next/font/google` and `@next/font/local`. For features and usage, please see the [Optimizing Fonts](/docs/basic-features/font-optimization.md) page.
+
+### Font function arguments
+
+For usage, review [Google Fonts](/docs/basic-features/font-optimization.md#google-fonts) and [Local Fonts](/docs/basic-features/font-optimization#local-fonts).
+
+| Key | `font/google` | `font/local` | Data type | Required |
+| ------------------------------------------- | ------------- | ------------ | -------------------------- | ----------------- |
+| [`src`](#src) | ❌ | ✅ | String or Array of Objects | Required |
+| [`weight`](#weight) | ✅ | ✅ | String or Array | Required/Optional |
+| [`style`](#style) | ✅ | ✅ | String or Array | Optional |
+| [`subsets`](#subsets) | ✅ | ❌ | Array of Strings | Optional |
+| [`axes`](#axes) | ✅ | ❌ | Array of Strings | Optional |
+| [`display`](#display) | ✅ | ✅ | String | Optional |
+| [`preload`](#preload) | ✅ | ✅ | Boolean | Optional |
+| [`fallback`](#fallback) | ✅ | ✅ | Array of Strings | Optional |
+| [`adjustFontFallback`](#adjustFontFallback) | ✅ | ✅ | Boolean or String | Optional |
+| [`variable`](#variable) | ✅ | ✅ | String | Optional |
+| [`declarations`](#declarations) | ❌ | ✅ | Array of Objects | Optional |
+
+### `src`
+
+The path of the font file as a string or an array of objects (with type `Array<{path: string, weight?: string, style?: string}>`) relative to the directory where the font loader function is called.
+
+Used in `@next/font/local`
+
+- Required
+
+Examples:
+
+- `src:'./fonts/my-font.woff2'` where `my-font.woff2` is placed in a directory named `fonts` inside the `app` directory
+- `src:[{path: './inter/Inter-Thin.ttf', weight: '100',},{path: './inter/Inter-Regular.ttf',weight: '400',},{path: './inter/Inter-Bold-Italic.ttf', weight: '700',style: 'italic',},]`
+- if the font loader function is called in `app/page.tsx` using `src:'../styles/fonts/my-font.ttf'`, then `my-font.ttf` is placed in `styles/fonts` at the root of the project
+
+### `weight`
+
+The font [`weight`](https://fonts.google.com/knowledge/glossary/weight) with the following possibilities:
+
+- A string with possible values of the weights available for the specific font or a range of values if it's a [variable](https://fonts.google.com/variablefonts) font
+- An array of weight values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `@next/font/google` only.
+
+Used in `@next/font/google` and `@next/font/local`
+
+- Required if the font being used is **not** [variable](https://fonts.google.com/variablefonts)
+
+Examples:
+
+- `weight: '400'`: A string for a single weight value - for the font [`Inter`](https://fonts.google.com/specimen/Inter?query=inter), the possible values are `'100'`, `'200'`, `'300'`, `'400'`, `'500'`, `'600'`, `'700'`, `'800'`, `'900'` or `'variable'` where `'variable'` is the default)
+- `weight: '100 900'`: A string for the range between `100` and `900` for a variable font
+- `weight: ['100','400','900']`: An array of 3 possible values for a non variable font
+
+### `style`
+
+The font [`style`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) with the following possibilities:
+
+- A string [value](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style#values) with default value of `'normal'`
+- An array of style values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `@next/font/google` only.
+
+Used in `@next/font/google` and `@next/font/local`
+
+- Optional
+
+Examples:
+
+- `style: 'italic'`: A string - it can be `normal` or `italic` for `@next/font/google`
+- `style: 'oblique'`: A string - it can take any value for `@next/font/local` but is expected to come from [standard font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style)
+- `style: ['italic','normal']`: An array of 2 values for `@next/font/google` - the values are from `normal` and `italic`
+
+### `subsets`
+
+The font [`subsets`](https://fonts.google.com/knowledge/glossary/subsetting) defined by an array of string values with the names of each subset you would like to be [preloaded](/docs/optimizing/fonts.md#specifying-a-subset). Fonts specified via `subsets` will have a link preload tag injected into the head when the [`preload`](/docs/api-reference/components/font.md#preload) option is true, which is the default.
+
+Used in `@next/font/google`
+
+- Optional
+
+Examples:
+
+- `subsets: ['latin']`: An array with the subset `latin`
+
+### `axes`
+
+Some variable fonts have extra `axes` that can be included. By default, only the font weight is included to keep the file size down. The possible values of `axes` depend on the specific font.
+
+Used in `@next/font/google`
+
+- Optional
+
+Examples:
+
+- `axes: ['slnt']`: An array with value `slnt` for the `Inter` variable font which has `slnt` as additional `axes` as shown [here](https://fonts.google.com/variablefonts?vfquery=inter#font-families). You can find the possible `axes` values for your font by using the filter on the [Google variable fonts page](https://fonts.google.com/variablefonts#font-families) and looking for axes other than `wght`
+
+### `display`
+
+The font [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) with possible string [values](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display#values) of `'auto'`, `'block'`, `'swap'`, `'fallback'` or `'optional'` with default value of `'optional'`.
+
+Used in `@next/font/google` and `@next/font/local`
+
+- Optional
+
+Examples:
+
+- `display: 'swap'`: A string assigned to the `swap` value
+
+### `preload`
+
+A boolean value that specifies whether the font should be [preloaded](/docs/optimizing/fonts#preloading) or not. The default is `true`.
+
+Used in `@next/font/google` and `@next/font/local`
+
+- Optional
+
+Examples:
+
+- `preload: false`
+
+### `fallback`
+
+The fallback font to use if the font cannot be loaded. An array of strings of fallback fonts with no default.
+
+- Optional
+
+Used in `@next/font/google` and `@next/font/local`
+
+Examples:
+
+- `fallback: ['system-ui', 'arial']`: An array setting the fallback fonts to `system-ui` or `arial`
+
+### `adjustFontFallback`
+
+- For `@next/font/google`: A boolean value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The default is `true`.
+- For `@next/font/local`: A string or boolean `false` value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The possible values are `'Arial'`, `'Times New Roman'` or `false`. The default is `'Arial'`.
+
+Used in `@next/font/google` and `@next/font/local`
+
+- Optional
+
+Examples:
+
+- `adjustFontFallback: false`: for ``@next/font/google`
+- `adjustFontFallback: 'Times New Roman'`: for `@next/font/local`
+
+### `variable`
+
+A string value to define the CSS variable name to be used if the style is applied with the [CSS variable method](#css-variables).
+
+Used in `@next/font/google` and `@next/font/local`
+
+- Optional
+
+Examples:
+
+- `variable: '--my-font'`: The CSS variable `--my-font` is declared
+
+### `declarations`
+
+An array of font face [descriptor](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face#descriptors) key-value pairs that define the generated `@font-face` further.
+
+Used in `@next/font/local`
+
+- Optional
+
+Examples:
+
+- `declarations: [{ prop: 'ascent-override', value: '90%' }]`
+
+## Applying Styles
+
+You can apply the font styles in three ways:
+
+- [`className`](#classname)
+- [`style`](#style)
+- [CSS Variables](#css-variables)
+
+### `className`
+
+Returns a read-only CSS `className` for the loaded font to be passed to an HTML element.
+
+```tsx
+<p className={inter.className}>Hello, Next.js!</p>
+```
+
+### `style`
+
+Returns a read-only CSS `style` object for the loaded font to be passed to an HTML element, including `style.fontFamily` to access the font family name and fallback fonts.
+
+```tsx
+<p style={inter.style}>Hello World</p>
+```
+
+### CSS Variables
+
+If you would like to set your styles in an external style sheet and specify additional options there, use the CSS variable method.
+
+In addition to importing the font, also import the CSS file where the CSS variable is defined and set the variable option of the font loader object as follows:
+
+```js
+// pages/index.js
+import { Inter } from '@next/font/google'
+import styles from '../styles/component.module.css'
+
+const inter = Inter({
+ variable: '--inter-font',
+})
+```
+
+To use the font, set the `className` of the parent container of the text you would like to style to the font loader's `variable` value and the `className` of the text to the `styles` property from the external CSS file.
+
+```js
+// pages/index.js
+<main className={inter.variable}>
+ <p className={styles.text}>Hello World</p>
+</main>
+```
+
+Define the `text` selector class in the `component.module.css` CSS file as follows:
+
+```css
+/* styles/component.module.css */
+.text {
+ font-family: var(--inter-font);
+ font-weight: 200;
+ font-style: italic;
+}
+```
+
+In the example above, the text `Hello World` is styled using the `Inter` font and the generated font fallback with `font-weight: 200` and `font-style: italic`.
+
+<!-- ### Using a font definitions file
+
+Every time you call the `localFont` or Google font function, that font will be hosted as one instance in your application. Therefore, if you need to use the same font in multiple places, you should load it in one place and import the related font object where you need it. This is done using a font definitions file.
+
+For example, create a `fonts.ts` file in a `styles` folder at the root of your app directory.
+
+Then, specify your font definitions as follows:
+
+```ts
+// styles/fonts.ts
+import { Inter, Lora, Source_Sans_Pro } from '@next/font/google';
+import localFont from '@next/font/local';
+
+// define your variable fonts
+const inter = Inter();
+const lora = Lora();
+// define 2 weights of a non-variable font
+const sourceCodePro400 = Source_Sans_Pro({ weight: '400' });
+const sourceCodePro700 = Source_Sans_Pro({ weight: '700' });
+// define a custom local font where GreatVibes-Regular.ttf is stored in the styles folder
+const greatVibes = localFont({ src: './GreatVibes-Regular.ttf' });
+
+export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes };
+```
+
+You can now use these definitions in your code as follows:
+
+```tsx
+// app/page.tsx
+import { inter, lora, sourceCodePro700, greatVibes } from '../styles/fonts';
+
+export default function Page() {
+ return (
+ <div>
+ <p className={inter.className}>Hello world using Inter font</p>
+ <p style={lora.style}>Hello world using Lora font</p>
+ <p className={sourceCodePro700.className}>
+ Hello world using Source_Sans_Pro font with weight 700
+ </p>
+ <p className={greatVibes.className}>My title in Great Vibes font</p>
+ </div>
+ );
+}
+```
+
+To make it easier to access the font definitions in your code, you can define a path alias in your `tsconfig.json` or `jsconfig.json` files as follows:
+
+```json
+// tsconfig.json
+{
+ "compilerOptions": {
+ "paths": {
+ "@/fonts": ["./styles/fonts"]
+ }
+ }
+}
+```
+
+You can now import any font definition as follows:
+
+```tsx
+// app/about/page.tsx
+import { greatVibes, sourceCodePro400 } from '@/fonts';
+``` -->
+
+## Next Steps
+
+<div class="card">
+ <a href="/docs/basic-features/font-optimization.md">
+ <b>Font Optimization</b>
+ <small>Learn how to optimize fonts with the Font module.</small>
+ </a>
+</div>
diff --git a/docs/api-reference/next/head.md b/docs/api-reference/next/head.md
new file mode 100644
index 0000000000000..96a6d14a5ea31
--- /dev/null
+++ b/docs/api-reference/next/head.md
@@ -0,0 +1,65 @@
+---
+description: Add custom elements to the `head` of your page with the built-in Head component.
+---
+
+# next/head
+
+<details>
+ <summary><b>Examples</b></summary>
+ <ul>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/head-elements">Head Elements</a></li>
+ <li><a href="https://github.com/vercel/next.js/tree/canary/examples/layout-component">Layout Component</a></li>
+ </ul>
+</details>
+
+We expose a built-in component for appending elements to the `head` of the page:
+
+```jsx
+import Head from 'next/head'
+
+function IndexPage() {
+ return (
+ <div>
+ <Head>
+ <title>My page title
+
+
+
Hello world!
+
+ )
+}
+
+export default IndexPage
+```
+
+To avoid duplicate tags in your `head` you can use the `key` property, which will make sure the tag is only rendered once, as in the following example:
+
+```jsx
+import Head from 'next/head'
+
+function IndexPage() {
+ return (
+
+
+ My page title
+
+
+
+
+
+
Hello world!
+
+ )
+}
+
+export default IndexPage
+```
+
+In this case only the second `` is rendered. `meta` tags with duplicate `key` attributes are automatically handled.
+
+> The contents of `head` get cleared upon unmounting the component, so make sure each page completely defines what it needs in `head`, without making assumptions about what other pages added.
+
+`title`, `meta` or any other elements (e.g. `script`) need to be contained as **direct** children of the `Head` element,
+or wrapped into maximum one level of `` or arrays—otherwise the tags won't be correctly picked up on client-side navigations.
+
+> We recommend using [next/script](/docs/basic-features/script.md) in your component instead of manually creating a `
+```
+
+Or by using the `dangerouslySetInnerHTML` property:
+
+```jsx
+
+```
+
+> **Note**: An `id` property must be assigned for inline scripts in order for Next.js to track and optimize the script.
+
+### Executing Additional Code
+
+Event handlers can be used with the Script component to execute additional code after a certain event occurs:
+
+- `onLoad`: Execute code after the script has finished loading.
+- `onReady`: Execute code after the script has finished loading and every time the component is mounted.
+- `onError`: Execute code if the script fails to load.
+
+```jsx
+import Script from 'next/script'
+
+export default function Page() {
+ return (
+ <>
+
+```
+
+The HTML [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) tag is used to embed any client-side JavaScript. It can either contain inline scripting statements (as shown in the example above) or point to an external script file via the `src` attribute.
+This example validates the name and roll number of a user. The `validateFormWithJS()` function does not allow an empty name field, and the roll number must be at least three digits long. The validation is performed when you hit the Submit button. You are not redirected to the next page until the given values are correct.
+
+
+
+#### Form Validation Using Regular Expressions
+
+JavaScript validation with Regular Expressions uses the `pattern` HTML attribute. A regular expression (commonly known as RegEx) is an object that describes a pattern of characters. You can only apply the `pattern` attribute to the `` element. This way, you can validate the input value using Regular Expressions (RegEx) by defining your own rules. Once again, if the value does not match the defined pattern, the input will give an error.
+The below example shows using the `pattern` attribute on an `input` element:
+
+```html
+
+```
+
+The password form field must only contain digits (0 to 9), lowercase alphabets (a to z) and it must be no more than 15 characters in length. No other characters (#,$,&, etc.) are allowed. The rule in RegEx is written as `[a-z0-9]{1,15}`.
+
+
+
+> To learn more about HTML forms, check out the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Learn/Forms).
+
+## Part 2: Project Setup
+
+In the following section you will be creating forms in React using Next.js.
+
+Create a new Next.js app. You can use the [create-next-app](https://nextjs.org/docs/getting-started#setup) for a quick start. In your command line terminal, run the following:
+
+```
+npx create-next-app
+```
+
+Answer the questions to create your project, and give it a name, this example uses [`next-forms`](https://github.com/vercel/next.js/tree/canary/examples/next-forms). Next `cd` into this directory, and run `npm run dev` or `yarn dev` command to start the development server.
+
+Open the URL printed in the terminal to ensure that your app is running successfully.
+
+## Part 3: Setting up a Next.js Form API Route
+
+Both the client and the server will be built using Next.js. For the server part, create an API endpoint where you will send the form data.
+
+Next.js offers a file-based system for routing that's built on the [concept of pages](/docs/basic-features/pages). Any file inside the folder `pages/api` is mapped to `/api/*` and will be treated as an API endpoint instead of a page. This [API endpoint](/docs/api-routes/introduction) is going to be server-side only.
+
+Go to `pages/api`, create a file called `form.js` and paste this code written in Node.js:
+
+```js
+export default function handler(req, res) {
+ // Get data submitted in request's body.
+ const body = req.body
+
+ // Optional logging to see the responses
+ // in the command line where next.js app is running.
+ console.log('body: ', body)
+
+ // Guard clause checks for first and last name,
+ // and returns early if they are not found
+ if (!body.first || !body.last) {
+ // Sends a HTTP bad request error code
+ return res.status(400).json({ data: 'First or last name not found' })
+ }
+
+ // Found the name.
+ // Sends a HTTP success code
+ res.status(200).json({ data: `${body.first} ${body.last}` })
+}
+```
+
+This form `handler` function will receive the request `req` from the client (i.e. submitted form data). And in return, it'll send a response `res` as JSON that will have both the first and the last name. You can access this API endpoint at `http://localhost:3000/api/form` or replace the localhost URL with an actual Vercel deployment when you deploy.
+
+> Moreover, you can also attach this API to a database like MongoDB or Google Sheets. This way, your submitted form data will be securely stored for later use. For this guide, no database is used. Instead, the same data is returned to the user to demo how it's done.
+
+### Form Submission without JavaScript
+
+You can now use `/api/form` relative endpoint inside the `action` attribute of the form. You are sending form data to the server when the form is submitted via `POST` HTTP method (which is used to send data).
+
+```html
+
+```
+
+If you submit this form, it will submit the data to the forms API endpoint `/api/form`. The server then responds, generally handling the data and loading the URL defined by the action attribute, causing a new page load. So in this case you'll be redirected to `http://localhost:3000/api/form` with the following response from the server.
+
+
+
+## Part 4: Configuring Forms in Next.js
+
+You have created a Next.js API Route for form submission. Now it's time to configure the client (the form itself) inside Next.js using React. The first step will be extending your knowledge of HTML forms and converting it into React (using [JSX](https://reactjs.org/docs/introducing-jsx.html)).
+
+Here's the same form in a [React function component](https://reactjs.org/docs/components-and-props.html) written using [JSX](https://reactjs.org/docs/introducing-jsx.html).
+
+```js
+export default function Form() {
+ return (
+
+ )
+}
+```
+
+Here's what changed:
+
+- The `for` attribute is changed to `htmlFor`. (Since `for` is a keyword associated with the "for" loop in JavaScript, React elements use `htmlFor` instead.)
+- The `action` attribute now has a relative URL which is the form API endpoint.
+
+This completes the basic structure of your Next.js-based form.
+
+> You can view the entire source code of [next-forms](https://github.com/vercel/next.js/tree/canary/examples/next-forms) example repo that we're creating here as a working example. Feel free to clone it and start right away. This demo is built with create-next-app, and you can preview the basic form CSS styles inside `/styles/global.css` file.
+
+
+
+## Part 5: Form Submission without JavaScript
+
+JavaScript brings interactivity to our web applications, but sometimes you need to control the JavaScript bundle from being too large, or your sites visitors might have JavaScript disabled.
+
+There are several reasons why users disable JavaScript:
+
+- Addressing bandwidth constraints
+- Increasing device (phone or laptop) battery life
+- For privacy so they won’t be tracked with analytical scripts
+
+Regardless of the reason, disabling JavaScript will impact site functionality partially, if not completely.
+
+Next open the `next-forms` directory. Inside the `/pages` directory, create a file `no-js-form.js`.
+
+> **Quick Tip**: In Next.js, a page is a React Component exported from a `.js`, `.jsx`, `.ts`, or `.tsx` file in the pages directory. Each page is associated with a route based on its file name.
+>
+> Example: If you create `pages/no-js-form.js`, it will be accessible at `your-domain.tld/no-js-form`.
+
+Let's use the same code from above:
+
+```js
+export default function PageWithoutJSbasedForm() {
+ return (
+
+ )
+}
+```
+
+With JavaScript disabled, when you hit the Submit button, an event is triggered, which collects the form data and sends it to our forms API endpoint as defined in the `action` attribute and using `POST` HTTP `method`. You'll be redirected to the `/api/form` endpoint since that's how form `action` works.
+
+The form data will be submitted on the server as a request `req` to the form handler function written above. It will process the data and return a JSON string as a response `res` with your submitted name included.
+
+> To improve the experience here, as a response you can redirect the user to a page and thank them for submitting the form.
+
+## Part 6: Form Submission with JavaScript Enabled
+
+Inside `/pages`, you'll create another file called `js-form.js`. This will create a `/js-form` page on your Next.js app.
+
+Now, as soon as the form is submitted, we prevent the form's default behavior of reloading the page. We'll take the form data, convert it to JSON string, and send it to our server, the API endpoint. Finally, our server will respond with the name submitted. All of this with a basic JavaScript `handleSubmit()` function.
+
+Here's what this function looks like. It's well documented for you to understand each step:
+
+```js
+export default function PageWithJSbasedForm() {
+ // Handles the submit event on form submit.
+ const handleSubmit = async (event) => {
+ // Stop the form from submitting and refreshing the page.
+ event.preventDefault()
+
+ // Get data from the form.
+ const data = {
+ first: event.target.first.value,
+ last: event.target.last.value,
+ }
+
+ // Send the data to the server in JSON format.
+ const JSONdata = JSON.stringify(data)
+
+ // API endpoint where we send form data.
+ const endpoint = '/api/form'
+
+ // Form the request for sending data to the server.
+ const options = {
+ // The method is POST because we are sending data.
+ method: 'POST',
+ // Tell the server we're sending JSON.
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ // Body of the request is the JSON data we created above.
+ body: JSONdata,
+ }
+
+ // Send the form data to our forms API on Vercel and get a response.
+ const response = await fetch(endpoint, options)
+
+ // Get the response data from server as JSON.
+ // If server returns the name submitted, that means the form works.
+ const result = await response.json()
+ alert(`Is this your full name: ${result.data}`)
+ }
+ return (
+ // We pass the event to the handleSubmit() function on submit.
+
+ )
+}
+```
+
+It's a Next.js page with a React function component called `PageWithJSbasedForm` with a `` element. For example, here's an SEO component with Create React App:
+
+```jsx
+// src/components/seo.js
+
+import { Helmet } from 'react-helmet'
+
+export default function SEO({ description, title, siteTitle }) {
+ return (
+
+ )
+}
+```
+
+And here's the same example using Next.js.
+
+```jsx
+// src/components/seo.js
+
+import Head from 'next/head'
+
+export default function SEO({ description, title, siteTitle }) {
+ return (
+
+ {`${title} | ${siteTitle}`}
+
+
+
+
+
+
+
+
+
+
+ )
+}
+```
+
+## Single-Page App (SPA)
+
+If you want to move your existing Create React App to Next.js and keep a Single-Page App, you can move your old application's entry point to an [Optional Catch-All Route](/docs/routing/dynamic-routes.md#optional-catch-all-routes) named `pages/[[...app]].js`.
+
+```jsx
+// pages/[[...app]].js
+
+import { useState, useEffect } from 'react'
+import CreateReactAppEntryPoint from '../components/app'
+
+function App() {
+ const [isMounted, setIsMounted] = useState(false)
+
+ useEffect(() => {
+ setIsMounted(true)
+ }, [])
+
+ if (!isMounted) {
+ return null
+ }
+
+ return
+}
+
+export default App
+```
+
+## Ejected Create React App
+
+If you've ejected Create React App, here are some things to consider:
+
+- If you have custom file loaders set up for CSS, Sass, or other assets, this is all built-in with Next.js.
+- If you've manually added [new JavaScript features](/docs/basic-features/supported-browsers-features.md#javascript-language-features) (e.g. Optional Chaining) or [Polyfills](/docs/basic-features/supported-browsers-features.md#polyfills), check to see what's included by default with Next.js.
+- If you have a custom code splitting setup, you can remove that. Next.js has automatic code splitting on a [per-page basis](/docs/basic-features/pages.md).
+- You can [customize your PostCSS setup](/docs/advanced-features/customizing-postcss-config.md#default-behavior) with Next.js without ejecting from the framework.
+- You should reference the default [Babel config](/docs/advanced-features/customizing-babel-config.md) and [Webpack config](/docs/api-reference/next.config.js/custom-webpack-config.md) of Next.js to see what's included by default.
+
+## Learn More
+
+You can learn more about Next.js by completing our [starter tutorial](https://nextjs.org/learn/basics/create-nextjs-app). If you have questions or if this guide didn't work for you, feel free to reach out to our community on [GitHub Discussions](https://github.com/vercel/next.js/discussions).
diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md
new file mode 100644
index 0000000000000..98031267bc2ff
--- /dev/null
+++ b/docs/migrating/from-gatsby.md
@@ -0,0 +1,319 @@
+---
+description: Learn how to transition an existing Gatsby project to Next.js.
+---
+
+# Migrating from Gatsby
+
+This guide will help you understand how to transition from an existing Gatsby project to Next.js. Migrating to Next.js will allow you to:
+
+- Choose which [data fetching](/docs/basic-features/data-fetching/overview.md) strategy you want on a per-page basis.
+- Use [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md) to update _existing_ pages by re-rendering them in the background as traffic comes in.
+- Use [API Routes](/docs/api-routes/introduction.md).
+
+And more! Let’s walk through a series of steps to complete the migration.
+
+## Updating `package.json` and dependencies
+
+The first step towards migrating to Next.js is to update `package.json` and dependencies. You should:
+
+- Remove all Gatsby-related packages (but keep `react` and `react-dom`).
+- Install `next`.
+- Add Next.js related commands to `scripts`. One is `next dev`, which runs a development server at `localhost:3000`. You should also add `next build` and `next start` for creating and starting a production build.
+
+Here's an example `package.json` ([view diff](https://github.com/leerob/gatsby-to-nextjs/pull/1/files#diff-b9cfc7f2cdf78a7f4b91a753d10865a2)):
+
+```json
+{
+ "scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "next": "latest",
+ "react": "latest",
+ "react-dom": "latest"
+ }
+}
+```
+
+## Static Assets and Compiled Output
+
+Gatsby uses the `public` directory for the compiled output, whereas Next.js uses it for static assets. Here are the steps for migration ([view diff](https://github.com/leerob/gatsby-to-nextjs/pull/1/files#diff-a084b794bc0759e7a6b77810e01874f2)):
+
+- Remove `.cache/` and `public` from `.gitignore` and delete both directories.
+- Rename Gatsby’s `static` directory as `public`.
+- Add `.next` to `.gitignore`.
+
+## Creating Routes
+
+Both Gatsby and Next support a `pages` directory, which uses [file-system based routing](/docs/routing/introduction.md). Gatsby's directory is `src/pages`, which is also [supported by Next.js](/docs/advanced-features/src-directory.md).
+
+Gatsby creates dynamic routes using the `createPages` API inside of `gatsby-node.js`. With Next, we can use [Dynamic Routes](/docs/routing/dynamic-routes.md) inside of `pages` to achieve the same effect. Rather than having a `template` directory, you can use the React component inside your dynamic route file. For example:
+
+- **Gatsby:** `createPages` API inside `gatsby-node.js` for each blog post, then have a template file at `src/templates/blog-post.js`.
+- **Next:** Create `pages/blog/[slug].js` which contains the blog post template. The value of `slug` is accessible through a [query parameter](/docs/routing/dynamic-routes.md). For example, the route `/blog/first-post` would forward the query object `{ 'slug': 'first-post' }` to `pages/blog/[slug].js` ([learn more here](/docs/basic-features/data-fetching/get-static-paths.md)).
+
+## Styling
+
+With Gatsby, global CSS imports are included in `gatsby-browser.js`. With Next, you should create a [custom `_app.js`](/docs/advanced-features/custom-app.md) for global CSS. When migrating, you can copy over your CSS imports directly and update the relative file path, if necessary. Next.js has [built-in CSS support](/docs/basic-features/built-in-css-support.md).
+
+## Links
+
+The Gatsby `Link` and Next.js [`Link`](/docs/api-reference/next/link.md) component have a slightly different API.
+
+```jsx
+// Gatsby
+
+import { Link } from 'gatsby'
+
+export default function Home() {
+ return blog
+}
+```
+
+```jsx
+// Next.js
+
+import Link from 'next/link'
+
+export default function Home() {
+ return blog
+}
+```
+
+Update any import statements, switch `to` to `href`.
+
+## Data Fetching
+
+The largest difference between Gatsby and Next.js is how data fetching is implemented. Gatsby is opinionated with GraphQL being the default strategy for retrieving data across your application. With Next.js, you get to choose which strategy you want (GraphQL is one supported option).
+
+Gatsby uses the `graphql` tag to query data in the pages of your site. This may include local data, remote data, or information about your site configuration. Gatsby only allows the creation of static pages. With Next.js, you can choose on a [per-page basis](/docs/basic-features/pages.md) which [data fetching strategy](/docs/basic-features/data-fetching/overview.md) you want. For example, `getServerSideProps` allows you to do server-side rendering. If you wanted to generate a static page, you'd export `getStaticProps` / `getStaticPaths` inside the page, rather than using `pageQuery`. For example:
+
+```js
+// src/pages/[slug].js
+
+// Install remark and remark-html
+import { remark } from 'remark'
+import html from 'remark-html'
+import { getPostBySlug, getAllPosts } from '../lib/blog'
+
+export async function getStaticProps({ params }) {
+ const post = getPostBySlug(params.slug)
+ const markdown = await remark()
+ .use(html)
+ .process(post.content || '')
+ const content = markdown.toString()
+
+ return {
+ props: {
+ ...post,
+ content,
+ },
+ }
+}
+
+export async function getStaticPaths() {
+ const posts = getAllPosts()
+
+ return {
+ paths: posts.map((post) => {
+ return {
+ params: {
+ slug: post.slug,
+ },
+ }
+ }),
+ fallback: false,
+ }
+}
+```
+
+You'll commonly see Gatsby plugins used for reading the file system (`gatsby-source-filesystem`), handling markdown files (`gatsby-transformer-remark`), and so on. For example, the popular starter blog example has [15 Gatsby specific packages](https://github.com/gatsbyjs/gatsby-starter-blog/blob/master/package.json). Next takes a different approach. It includes common features directly inside the framework, and gives the user full control over integrations with external packages. For example, rather than abstracting reading from the file system to a plugin, you can use the native Node.js `fs` package inside `getStaticProps` / `getStaticPaths` to read from the file system.
+
+```js
+// src/lib/blog.js
+
+// Install gray-matter and date-fns
+import matter from 'gray-matter'
+import { parseISO, format } from 'date-fns'
+import fs from 'fs'
+import { join } from 'path'
+
+// Add markdown files in `src/content/blog`
+const postsDirectory = join(process.cwd(), 'src', 'content', 'blog')
+
+export function getPostBySlug(slug) {
+ const realSlug = slug.replace(/\.md$/, '')
+ const fullPath = join(postsDirectory, `${realSlug}.md`)
+ const fileContents = fs.readFileSync(fullPath, 'utf8')
+ const { data, content } = matter(fileContents)
+ const date = format(parseISO(data.date), 'MMMM dd, yyyy')
+
+ return { slug: realSlug, frontmatter: { ...data, date }, content }
+}
+
+export function getAllPosts() {
+ const slugs = fs.readdirSync(postsDirectory)
+ const posts = slugs.map((slug) => getPostBySlug(slug))
+
+ return posts
+}
+```
+
+## Image Component and Image Optimization
+
+Next.js has a built-in [Image Component and Automatic Image Optimization](/docs/basic-features/image-optimization.md).
+
+The Next.js Image Component, [`next/image`](/docs/api-reference/next/image.md), is an extension of the HTML `` element, evolved for the modern web.
+
+The Automatic Image Optimization allows for resizing, optimizing, and serving images in modern formats like [WebP](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types) when the browser supports it. This avoids shipping large images to devices with a smaller viewport. It also allows Next.js to automatically adopt future image formats and serve them to browsers that support those formats.
+
+### Migrating from Gatsby Image
+
+Instead of optimizing images at build time, Next.js optimizes images on-demand, as users request them. Unlike static site generators and static-only solutions, your build times aren't increased, whether shipping 10 images or 10 million images.
+
+This means you can remove common Gatsby plugins like:
+
+- `gatsby-image`
+- `gatsby-transformer-sharp`
+- `gatsby-plugin-sharp`
+
+Instead, use the built-in [`next/image`](/docs/api-reference/next/image.md) component and [Automatic Image Optimization](/docs/basic-features/image-optimization.md).
+
+> The `next/image` component's default loader is not supported when using [`next export`](/docs/advanced-features/static-html-export.md). However, other loader options will work.
+
+```jsx
+import Image from 'next/image'
+import profilePic from '../public/me.png'
+
+export default function Home() {
+ return (
+ <>
+
My Homepage
+
+
Welcome to my homepage!
+
+ )
+}
+```
+
+## Site Configuration
+
+With Gatsby, your site's metadata (name, description, etc.) is located inside `gatsby-config.js`. This is then exposed through the GraphQL API and consumed through a `pageQuery` or a static query inside a component.
+
+With Next.js, we recommend creating a config file similar to below. You can then import this file anywhere without having to use GraphQL to access your site's metadata.
+
+```js
+// src/config.js
+
+export default {
+ title: 'Starter Blog',
+ author: {
+ name: 'Lee Robinson',
+ summary: 'who loves Next.js.',
+ },
+ description: 'A starter blog converting Gatsby -> Next.',
+ social: {
+ twitter: 'leeerob',
+ },
+}
+```
+
+## Search Engine Optimization
+
+Most Gatsby examples use `react-helmet` to assist with adding `meta` tags for proper SEO. With Next.js, we use [`next/head`](/docs/api-reference/next/head.md) to add `meta` tags to your `` element. For example, here's an SEO component with Gatsby:
+
+```js
+// src/components/seo.js
+
+import { Helmet } from 'react-helmet'
+
+export default function SEO({ description, title, siteTitle }) {
+ return (
+
+ )
+}
+```
+
+And here's the same example using Next.js, including reading from a site config file.
+
+```js
+// src/components/seo.js
+
+import Head from 'next/head'
+import config from '../config'
+
+export default function SEO({ description, title }) {
+ const siteTitle = config.title
+
+ return (
+
+ {`${title} | ${siteTitle}`}
+
+
+
+
+
+
+
+
+
+
+ )
+}
+```
+
+## Learn more
+
+Take a look at [this pull request](https://github.com/leerob/gatsby-to-nextjs/pull/1) for more details on how an app can be migrated from Gatsby to Next.js. If you have questions or if this guide didn't work for you, feel free to reach out to our community on [GitHub Discussions](https://github.com/vercel/next.js/discussions).
diff --git a/docs/migrating/from-react-router.md b/docs/migrating/from-react-router.md
new file mode 100644
index 0000000000000..1174eaa5ed3c9
--- /dev/null
+++ b/docs/migrating/from-react-router.md
@@ -0,0 +1,175 @@
+---
+description: Learn how to migrate from React Router to file-system based routes with Next.js.
+---
+
+# Migrating from React Router
+
+This guide will help you understand how to transition from [React Router](https://reactrouter.com) to [file-system based](/docs/routing/introduction.md) routes with Next.js. Using [`next/link`](/docs/api-reference/next/link.md) and [`next/router`](/docs/api-reference/next/router.md) will allow you to:
+
+- Decrease bundle size by removing React Router as a dependency.
+- Define your application routes through the file system.
+- Utilize the latest improvements to the Next.js framework.
+
+## Basics
+
+First, uninstall React Router. You'll be migrating to the built-in routing with Next.js.
+
+```jsx
+npm uninstall react-router-dom
+```
+
+The `Link` component for performing client-side route transitions is slightly different from React Router.
+
+```jsx
+// Before (React Router)
+import { Link } from 'react-router-dom'
+
+export default function App() {
+ return About
+}
+
+// After (Next.js)
+import Link from 'next/link'
+
+export default function App() {
+ return (
+
+ About
+
+ )
+}
+```
+
+Most React applications that use React Router have a top-level navigation file, containing a list of routes. For example:
+
+```jsx
+import { BrowserRouter as Router, Switch, Route } from 'react-router-dom'
+
+export default function App() {
+ return (
+
+
+
+
About
+
+
+
Blog
+
+
+
Home
+
+
+
+ )
+}
+```
+
+With Next.js, you can express the same application structure in the file system. When a file is added to the [`pages`](/docs/basic-features/pages.md) directory it's automatically available as a route.
+
+- `pages/about.js` → `/about`
+- `pages/blog.js` → `/blog`
+- `pages/index.js` → `/`
+
+## Nested Routes
+
+In the example below, routes like `/blog/my-post` would render the `Post` component. If a slug was not provided, it would render the list of all blog posts.
+
+```jsx
+import {
+ BrowserRouter as Router,
+ Switch,
+ Route,
+ useRouteMatch,
+ useParams,
+} from 'react-router-dom'
+
+export default function Blog() {
+ // Nested route under /blog
+ const match = useRouteMatch()
+
+ return (
+
+
+
+
+
+
+
+}
+```
+
+Rather than using the `:slug` syntax inside your `Route` component, Next.js uses the `[slug]` syntax in the file name for [Dynamic Routes](/docs/routing/dynamic-routes.md). We can transform this to Next.js by creating two new files, `pages/blog/index.js` (showing all pages) and `pages/blog/[slug].js` (showing an individual post).
+
+```jsx
+// pages/blog/index.js
+
+export default function Blog() {
+ return
+}
+```
+
+## Server Rendering
+
+Next.js has built-in support for [Server-side Rendering](/docs/basic-features/pages#server-side-rendering.md). This means you can remove any instances of `StaticRouter` in your code.
+
+## Code Splitting
+
+Next.js has built-in support for [Code Splitting](https://reactrouter.com/web/guides/code-splitting). This means you can remove any instances of:
+
+- `@loadable/server`, `@loadable/babel-plugin`, and `@loadable/webpack-plugin`
+- Modifications to your `.babelrc` for `@loadable/babel-plugin`
+
+Each file inside your `pages/` directory will be code split into its own JavaScript bundle during the build process. Next.js [also supports](/docs/basic-features/supported-browsers-features.md#javascript-language-features) ES2020 dynamic `import()` for JavaScript. With it you can import JavaScript modules dynamically and work with them. They also work with SSR.
+
+For more information, read about [Dynamic Imports](https://nextjs.org/docs/advanced-features/dynamic-import).
+
+## Scroll Restoration
+
+Next.js has built-in support for [Scroll Restoration](https://reactrouter.com/web/guides/scroll-restoration). This means you can remove any custom `ScrollToTop` components you have defined.
+
+The default behavior of `next/link` and `next/router` is to scroll to the top of the page. You can also [disable this](https://nextjs.org/docs/api-reference/next/link#disable-scrolling-to-the-top-of-the-page) if you prefer.
+
+## Learn More
+
+For more information on what to do next, we recommend the following sections:
+
+
+
+
+Next.js has been designed for gradual adoption. With Next.js, you can continue using your existing code and add as much (or as little) React as you need. By starting small and incrementally adding more pages, you can prevent derailing feature work by avoiding a complete rewrite.
+
+## Strategies
+
+### Subpath
+
+The first strategy is to configure your server or proxy such that, everything under a specific subpath points to a Next.js app. For example, your existing website might be at `example.com`, and you might configure your proxy such that `example.com/store` serves a Next.js e-commerce store.
+
+Using [`basePath`](/docs/api-reference/next.config.js/basepath.md), you can configure your Next.js application's assets and links to automatically work with your new subpath `/store`. Since each page in Next.js is its own [standalone route](/docs/routing/introduction.md), pages like `pages/products.js` will route to `example.com/store/products` in your application.
+
+```jsx
+// next.config.js
+
+module.exports = {
+ basePath: '/store',
+}
+```
+
+To learn more about `basePath`, take a look at our [documentation](/docs/api-reference/next.config.js/basepath.md).
+
+### Rewrites
+
+The second strategy is to create a new Next.js app that points to the root URL of your domain. Then, you can use [`rewrites`](/docs/api-reference/next.config.js/rewrites.md) inside `next.config.js` to have some subpaths to be proxied to your existing app.
+
+For example, let's say you created a Next.js app to be served from `example.com` with the following `next.config.js`. Now, requests for the pages you’ve added to this Next.js app (e.g. `/about` if you’ve added `pages/about.js`) will be handled by Next.js, and requests for any other route (e.g. `/dashboard`) will be proxied to `proxy.example.com`.
+
+> **Note:** If you use [fallback: true/'blocking'](/docs/api-reference/data-fetching/get-static-paths#fallback-true) in `getStaticPaths`, the catch-all fallback `rewrites` defined in `next.config.js` will not be run. They are instead caught by the `getStaticPaths` fallback.
+
+```jsx
+// next.config.js
+
+module.exports = {
+ async rewrites() {
+ return {
+ // After checking all Next.js pages (including dynamic routes)
+ // and static files we proxy any other requests
+ fallback: [
+ {
+ source: '/:path*',
+ destination: `https://proxy.example.com/:path*`,
+ },
+ ],
+ }
+
+ // For versions of Next.js < v10.1 you can use a no-op rewrite instead
+ return [
+ // we need to define a no-op rewrite to trigger checking
+ // all pages/static files before we attempt proxying
+ {
+ source: '/:path*',
+ destination: '/:path*',
+ },
+ {
+ source: '/:path*',
+ destination: `https://proxy.example.com/:path*`,
+ },
+ ]
+ },
+}
+```
+
+To learn more about rewrites, take a look at our [documentation](/docs/api-reference/next.config.js/rewrites.md).
+
+> **Note:** If you are incrementally migrating to a dynamic route (e.g. `[slug].js`) and using `fallback: true` or `fallback: 'blocking'` along with a fallback `rewrite`, ensure you consider the case where pages are not found. When Next.js matches the dynamic route it stops checking any further routes. Using `notFound: true` in `getStaticProps` will return the 404 page without applying the fallback `rewrite`. If this is not desired, you can use `getServerSideProps` with `stale-while-revalidate` Cache-Control headers when returning your props. Then, you can _manually_ proxy to your existing backend using something like [http-proxy](https://github.com/vercel/next.js/discussions/38839#discussioncomment-3744442) instead of returning `notFound: true`.
+
+### Micro-Frontends with Monorepos and Subdomains
+
+Next.js and [Vercel](https://vercel.com) make it straightforward to adopt micro frontends and deploy as a [monorepo](https://vercel.com/blog/monorepos-are-changing-how-teams-build-software?utm_source=next-site&utm_medium=docs&utm_campaign=next-website). This allows you to use [subdomains](https://demo.vercel.pub/platforms-starter-kit) to adopt new applications incrementally. Some benefits of micro-frontends:
+
+- Smaller, more cohesive and maintainable codebases.
+- More scalable organizations with decoupled, autonomous teams.
+- The ability to upgrade, update, or even rewrite parts of the frontend in a more incremental fashion.
+
+Once your monorepo is set up, push changes to your Git repository as usual and you'll see the commits deployed to the Vercel projects you've connected.
+
+## Conclusion
+
+To learn more, read about [subpaths](/docs/api-reference/next.config.js/basepath.md) and [rewrites](/docs/api-reference/next.config.js/rewrites.md) or [deploy a Next.js monorepo](https://vercel.com/templates/next.js/monorepo-turborepo).
diff --git a/docs/routing/dynamic-routes.md b/docs/routing/dynamic-routes.md
new file mode 100644
index 0000000000000..87c02e856791d
--- /dev/null
+++ b/docs/routing/dynamic-routes.md
@@ -0,0 +1,154 @@
+---
+description: Dynamic Routes are pages that allow you to add custom params to your URLs. Start creating Dynamic Routes and learn more here.
+---
+
+# Dynamic Routes
+
+
+ Examples
+
+
+
+Defining routes by using predefined paths is not always enough for complex applications. In Next.js you can add brackets to a page (`[param]`) to create a dynamic route (a.k.a. url slugs, pretty urls, and others).
+
+Consider the following page `pages/post/[pid].js`:
+
+```jsx
+import { useRouter } from 'next/router'
+
+const Post = () => {
+ const router = useRouter()
+ const { pid } = router.query
+
+ return
Post: {pid}
+}
+
+export default Post
+```
+
+Any route like `/post/1`, `/post/abc`, etc. will be matched by `pages/post/[pid].js`. The matched path parameter will be sent as a query parameter to the page, and it will be merged with the other query parameters.
+
+For example, the route `/post/abc` will have the following `query` object:
+
+```json
+{ "pid": "abc" }
+```
+
+Similarly, the route `/post/abc?foo=bar` will have the following `query` object:
+
+```json
+{ "foo": "bar", "pid": "abc" }
+```
+
+However, route parameters will override query parameters with the same name. For example, the route `/post/abc?pid=123` will have the following `query` object:
+
+```json
+{ "pid": "abc" }
+```
+
+Multiple dynamic route segments work the same way. The page `pages/post/[pid]/[comment].js` will match the route `/post/abc/a-comment` and its `query` object will be:
+
+```json
+{ "pid": "abc", "comment": "a-comment" }
+```
+
+Client-side navigations to dynamic routes are handled with [`next/link`](/docs/api-reference/next/link.md). If we wanted to have links to the routes used above it will look like this:
+
+```jsx
+import Link from 'next/link'
+
+function Home() {
+ return (
+
+
+ Go to pages/post/[pid].js
+
+
+ Also goes to pages/post/[pid].js
+
+
+
+ Go to pages/post/[pid]/[comment].js
+
+
+
+ )
+}
+
+export default Home
+```
+
+Read our docs for [Linking between pages](/docs/routing/introduction.md#linking-between-pages) to learn more.
+
+### Catch all routes
+
+
+ Examples
+
+
+
+Dynamic routes can be extended to catch all paths by adding three dots (`...`) inside the brackets. For example:
+
+- `pages/post/[...slug].js` matches `/post/a`, but also `/post/a/b`, `/post/a/b/c` and so on.
+
+> **Note**: You can use names other than `slug`, such as: `[...param]`
+
+Matched parameters will be sent as a query parameter (`slug` in the example) to the page, and it will always be an array, so, the path `/post/a` will have the following `query` object:
+
+```json
+{ "slug": ["a"] }
+```
+
+And in the case of `/post/a/b`, and any other matching path, new parameters will be added to the array, like so:
+
+```json
+{ "slug": ["a", "b"] }
+```
+
+### Optional catch all routes
+
+Catch all routes can be made optional by including the parameter in double brackets (`[[...slug]]`).
+
+For example, `pages/post/[[...slug]].js` will match `/post`, `/post/a`, `/post/a/b`, and so on.
+
+The main difference between catch all and optional catch all routes is that with optional, the route without the parameter is also matched (`/post` in the example above).
+
+The `query` objects are as follows:
+
+```json
+{ } // GET `/post` (empty object)
+{ "slug": ["a"] } // `GET /post/a` (single-element array)
+{ "slug": ["a", "b"] } // `GET /post/a/b` (multi-element array)
+```
+
+## Caveats
+
+- Predefined routes take precedence over dynamic routes, and dynamic routes over catch all routes. Take a look at the following examples:
+ - `pages/post/create.js` - Will match `/post/create`
+ - `pages/post/[pid].js` - Will match `/post/1`, `/post/abc`, etc. But not `/post/create`
+ - `pages/post/[...slug].js` - Will match `/post/1/2`, `/post/a/b/c`, etc. But not `/post/create`, `/post/abc`
+- Pages that are statically optimized by [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) will be hydrated without their route parameters provided, i.e `query` will be an empty object (`{}`).
+
+ After hydration, Next.js will trigger an update to your application to provide the route parameters in the `query` object.
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+
diff --git a/docs/routing/imperatively.md b/docs/routing/imperatively.md
new file mode 100644
index 0000000000000..f3c4e589bb83b
--- /dev/null
+++ b/docs/routing/imperatively.md
@@ -0,0 +1,30 @@
+---
+description: Client-side navigations are also possible using the Next.js Router instead of the Link component. Learn more here.
+---
+
+# Imperatively
+
+
+ Examples
+
+
+
+[`next/link`](/docs/api-reference/next/link.md) should be able to cover most of your routing needs, but you can also do client-side navigations without it, take a look at the [documentation for `next/router`](/docs/api-reference/next/router.md).
+
+The following example shows how to do basic page navigations with [`useRouter`](/docs/api-reference/next/router.md#useRouter):
+
+```jsx
+import { useRouter } from 'next/router'
+
+export default function ReadMore() {
+ const router = useRouter()
+
+ return (
+
+ )
+}
+```
diff --git a/docs/routing/introduction.md b/docs/routing/introduction.md
new file mode 100644
index 0000000000000..c19a59486c9b1
--- /dev/null
+++ b/docs/routing/introduction.md
@@ -0,0 +1,160 @@
+---
+description: Next.js has a built-in, opinionated, and file-system based Router. You can learn how it works here.
+---
+
+# Routing
+
+Next.js has a file-system based router built on the [concept of pages](/docs/basic-features/pages.md).
+
+When a file is added to the `pages` directory, it's automatically available as a route.
+
+The files inside the `pages` directory can be used to define most common patterns.
+
+#### Index routes
+
+The router will automatically route files named `index` to the root of the directory.
+
+- `pages/index.js` → `/`
+- `pages/blog/index.js` → `/blog`
+
+#### Nested routes
+
+The router supports nested files. If you create a nested folder structure, files will automatically be routed in the same way still.
+
+- `pages/blog/first-post.js` → `/blog/first-post`
+- `pages/dashboard/settings/username.js` → `/dashboard/settings/username`
+
+#### Dynamic route segments
+
+To match a dynamic segment, you can use the bracket syntax. This allows you to match named parameters.
+
+- `pages/blog/[slug].js` → `/blog/:slug` (`/blog/hello-world`)
+- `pages/[username]/settings.js` → `/:username/settings` (`/foo/settings`)
+- `pages/post/[...all].js` → `/post/*` (`/post/2020/id/title`)
+
+> Check out the [Dynamic Routes documentation](/docs/routing/dynamic-routes.md) to learn more about how they work.
+
+## Linking between pages
+
+The Next.js router allows you to do client-side route transitions between pages, similar to a single-page application.
+
+A React component called `Link` is provided to do this client-side route transition.
+
+```jsx
+import Link from 'next/link'
+
+function Home() {
+ return (
+
+
+ Home
+
+
+ About Us
+
+
+ Blog Post
+
+
+ )
+}
+
+export default Home
+```
+
+The example above uses multiple links. Each one maps a path (`href`) to a known page:
+
+- `/` → `pages/index.js`
+- `/about` → `pages/about.js`
+- `/blog/hello-world` → `pages/blog/[slug].js`
+
+Any `` in the viewport (initially or through scroll) will be prefetched by default (including the corresponding data) for pages using [Static Generation](/docs/basic-features/data-fetching/get-static-props.md). The corresponding data for [server-rendered](/docs/basic-features/data-fetching/get-server-side-props.md) routes is fetched _only when_ the `` is clicked.
+
+### Linking to dynamic paths
+
+You can also use interpolation to create the path, which comes in handy for [dynamic route segments](#dynamic-route-segments). For example, to show a list of posts which have been passed to the component as a prop:
+
+```jsx
+import Link from 'next/link'
+
+function Posts({ posts }) {
+ return (
+
+ {posts.map((post) => (
+
+
+ {post.title}
+
+
+ ))}
+
+ )
+}
+
+export default Posts
+```
+
+> [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) is used in the example to keep the path utf-8 compatible.
+
+Alternatively, using a URL Object:
+
+```jsx
+import Link from 'next/link'
+
+function Posts({ posts }) {
+ return (
+
+ {posts.map((post) => (
+
+
+ {post.title}
+
+
+ ))}
+
+ )
+}
+
+export default Posts
+```
+
+Now, instead of using interpolation to create the path, we use a URL object in `href` where:
+
+- `pathname` is the name of the page in the `pages` directory. `/blog/[slug]` in this case.
+- `query` is an object with the dynamic segment. `slug` in this case.
+
+## Injecting the router
+
+
+ Examples
+
+
+
+To access the [`router` object](/docs/api-reference/next/router.md#router-object) in a React component you can use [`useRouter`](/docs/api-reference/next/router.md#useRouter) or [`withRouter`](/docs/api-reference/next/router.md#withRouter).
+
+In general we recommend using [`useRouter`](/docs/api-reference/next/router.md#useRouter).
+
+## Learn more
+
+The router is divided in multiple parts:
+
+
diff --git a/docs/routing/shallow-routing.md b/docs/routing/shallow-routing.md
new file mode 100644
index 0000000000000..dbb3f13250ab5
--- /dev/null
+++ b/docs/routing/shallow-routing.md
@@ -0,0 +1,65 @@
+---
+description: You can use shallow routing to change the URL without triggering a new page change. Learn more here.
+---
+
+# Shallow Routing
+
+
+ Examples
+
+
+
+Shallow routing allows you to change the URL without running data fetching methods again, that includes [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md), [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md), and [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md).
+
+You'll receive the updated `pathname` and the `query` via the [`router` object](/docs/api-reference/next/router.md#router-object) (added by [`useRouter`](/docs/api-reference/next/router.md#useRouter) or [`withRouter`](/docs/api-reference/next/router.md#withRouter)), without losing state.
+
+To enable shallow routing, set the `shallow` option to `true`. Consider the following example:
+
+```jsx
+import { useEffect } from 'react'
+import { useRouter } from 'next/router'
+
+// Current URL is '/'
+function Page() {
+ const router = useRouter()
+
+ useEffect(() => {
+ // Always do navigations after the first render
+ router.push('/?counter=10', undefined, { shallow: true })
+ }, [])
+
+ useEffect(() => {
+ // The counter changed!
+ }, [router.query.counter])
+}
+
+export default Page
+```
+
+The URL will get updated to `/?counter=10`. and the page won't get replaced, only the state of the route is changed.
+
+You can also watch for URL changes via [`componentDidUpdate`](https://reactjs.org/docs/react-component.html#componentdidupdate) as shown below:
+
+```jsx
+componentDidUpdate(prevProps) {
+ const { pathname, query } = this.props.router
+ // verify props have changed to avoid an infinite loop
+ if (query.counter !== prevProps.router.query.counter) {
+ // fetch data based on the new query
+ }
+}
+```
+
+## Caveats
+
+Shallow routing **only** works for URL changes in the current page. For example, let's assume we have another page called `pages/about.js`, and you run this:
+
+```jsx
+router.push('/?counter=10', '/about?counter=10', { shallow: true })
+```
+
+Since that's a new page, it'll unload the current page, load the new one and wait for data fetching even though we asked to do shallow routing.
+
+When shallow routing is used with middleware it will not ensure the new page matches the current page like previously done without middleware. This is due to middleware being able to rewrite dynamically and can't be verified client-side without a data fetch which is skipped with shallow, so a shallow route change must always be treated as shallow.
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 0000000000000..7414761d37c3b
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,503 @@
+---
+description: Learn how to set up Next.js with three commonly used testing tools — Cypress, Playwright, Jest, and React Testing Library.
+---
+
+# Testing
+
+
+ Examples
+
+
+
+Learn how to set up Next.js with commonly used testing tools: [Cypress](https://nextjs.org/docs/testing#cypress), [Playwright](https://nextjs.org/docs/testing#playwright), and [Jest with React Testing Library](https://nextjs.org/docs/testing#jest-and-react-testing-library).
+
+## Cypress
+
+Cypress is a test runner used for **End-to-End (E2E)** and **Integration Testing**.
+
+### Quickstart
+
+You can use `create-next-app` with the [with-cypress example](https://github.com/vercel/next.js/tree/canary/examples/with-cypress) to quickly get started.
+
+```bash
+npx create-next-app@latest --example with-cypress with-cypress-app
+```
+
+### Manual setup
+
+To get started with Cypress, install the `cypress` package:
+
+```bash
+npm install --save-dev cypress
+```
+
+Add Cypress to the `package.json` scripts field:
+
+```json
+"scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "start": "next start",
+ "cypress": "cypress open",
+}
+```
+
+Run Cypress for the first time to generate examples that use their recommended folder structure:
+
+```bash
+npm run cypress
+```
+
+You can look through the generated examples and the [Writing Your First Test](https://docs.cypress.io/guides/getting-started/writing-your-first-test) section of the Cypress Documentation to help you get familiar with Cypress.
+
+### Creating your first Cypress integration test
+
+Assuming the following two Next.js pages:
+
+```jsx
+// pages/index.js
+import Link from 'next/link'
+
+export default function Home() {
+ return (
+
+ )
+}
+```
+
+```jsx
+// pages/about.js
+export default function About() {
+ return (
+
+
About Page
+
+ )
+}
+```
+
+Add a test to check your navigation is working correctly:
+
+```jsx
+// cypress/integration/app.spec.js
+
+describe('Navigation', () => {
+ it('should navigate to the about page', () => {
+ // Start from the index page
+ cy.visit('http://localhost:3000/')
+
+ // Find a link with an href attribute containing "about" and click it
+ cy.get('a[href*="about"]').click()
+
+ // The new url should include "/about"
+ cy.url().should('include', '/about')
+
+ // The new page should contain an h1 with "About page"
+ cy.get('h1').contains('About Page')
+ })
+})
+```
+
+You can use `cy.visit("/")` instead of `cy.visit("http://localhost:3000/")` if you add `baseUrl: 'http://localhost:3000'` to the `cypress.config.js` configuration file.
+
+### Running your Cypress tests
+
+Since Cypress is testing a real Next.js application, it requires the Next.js server to be running prior to starting Cypress. We recommend running your tests against your production code to more closely resemble how your application will behave.
+
+Run `npm run build` and `npm run start`, then run `npm run cypress` in another terminal window to start Cypress.
+
+> **Note:** Alternatively, you can install the `start-server-and-test` package and add it to the `package.json` scripts field: `"test": "start-server-and-test start http://localhost:3000 cypress"` to start the Next.js production server in conjunction with Cypress. Remember to rebuild your application after new changes.
+
+### Getting ready for Continuous Integration (CI)
+
+You will have noticed that running Cypress so far has opened an interactive browser which is not ideal for CI environments. You can also run Cypress headlessly using the `cypress run` command:
+
+```json
+// package.json
+
+"scripts": {
+ //...
+ "cypress": "cypress open",
+ "cypress:headless": "cypress run",
+ "e2e": "start-server-and-test start http://localhost:3000 cypress",
+ "e2e:headless": "start-server-and-test start http://localhost:3000 cypress:headless"
+}
+```
+
+You can learn more about Cypress and Continuous Integration from these resources:
+
+- [Cypress Continuous Integration Docs](https://docs.cypress.io/guides/continuous-integration/introduction)
+- [Cypress GitHub Actions Guide](https://on.cypress.io/github-actions)
+- [Official Cypress GitHub Action](https://github.com/cypress-io/github-action)
+
+## Playwright
+
+Playwright is a testing framework that lets you automate Chromium, Firefox, and WebKit with a single API. You can use it to write **End-to-End (E2E)** and **Integration** tests across all platforms.
+
+### Quickstart
+
+The fastest way to get started is to use `create-next-app` with the [with-playwright example](https://github.com/vercel/next.js/tree/canary/examples/with-playwright). This will create a Next.js project complete with Playwright all set up.
+
+```bash
+npx create-next-app@latest --example with-playwright with-playwright-app
+```
+
+### Manual setup
+
+You can also use `npm init playwright` to add Playwright to an existing `NPM` project.
+
+To manually get started with Playwright, install the `@playwright/test` package:
+
+```bash
+npm install --save-dev @playwright/test
+```
+
+Add Playwright to the `package.json` scripts field:
+
+```json
+"scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "start": "next start",
+ "test:e2e": "playwright test",
+}
+```
+
+### Creating your first Playwright end-to-end test
+
+Assuming the following two Next.js pages:
+
+```jsx
+// pages/index.js
+import Link from 'next/link'
+
+export default function Home() {
+ return (
+
+ )
+}
+```
+
+```jsx
+// pages/about.js
+export default function About() {
+ return (
+
+
About Page
+
+ )
+}
+```
+
+Add a test to verify that your navigation is working correctly:
+
+```jsx
+// e2e/example.spec.ts
+
+import { test, expect } from '@playwright/test'
+
+test('should navigate to the about page', async ({ page }) => {
+ // Start from the index page (the baseURL is set via the webServer in the playwright.config.ts)
+ await page.goto('http://localhost:3000/')
+ // Find an element with the text 'About Page' and click on it
+ await page.click('text=About')
+ // The new URL should be "/about" (baseURL is used there)
+ await expect(page).toHaveURL('http://localhost:3000/about')
+ // The new page should contain an h1 with "About Page"
+ await expect(page.locator('h1')).toContainText('About Page')
+})
+```
+
+You can use `page.goto("/")` instead of `page.goto("http://localhost:3000/")`, if you add [`"baseURL": "http://localhost:3000"`](https://playwright.dev/docs/api/class-testoptions#test-options-base-url) to the `playwright.config.ts` configuration file.
+
+### Running your Playwright tests
+
+Since Playwright is testing a real Next.js application, it requires the Next.js server to be running prior to starting Playwright. It is recommended to run your tests against your production code to more closely resemble how your application will behave.
+
+Run `npm run build` and `npm run start`, then run `npm run test:e2e` in another terminal window to run the Playwright tests.
+
+> **Note:** Alternatively, you can use the [`webServer`](https://playwright.dev/docs/test-advanced#launching-a-development-web-server-during-the-tests) feature to let Playwright start the development server and wait until it's fully available.
+
+### Running Playwright on Continuous Integration (CI)
+
+Playwright will by default run your tests in the [headless mode](https://playwright.dev/docs/ci#running-headed). To install all the Playwright dependencies, run `npx playwright install-deps`.
+
+You can learn more about Playwright and Continuous Integration from these resources:
+
+- [Getting started with Playwright](https://playwright.dev/docs/intro)
+- [Use a development server](https://playwright.dev/docs/test-advanced#launching-a-development-web-server-during-the-tests)
+- [Playwright on your CI provider](https://playwright.dev/docs/ci)
+
+## Jest and React Testing Library
+
+Jest and React Testing Library are frequently used together for **Unit Testing**. There are three ways you can start using Jest within your Next.js application:
+
+1. Using one of our [quickstart examples](https://nextjs.org/docs/testing#quickstart-2)
+2. With the [Next.js Rust Compiler](https://nextjs.org/docs/testing#setting-up-jest-with-the-rust-compiler)
+3. With [Babel](https://nextjs.org/docs/testing#setting-up-jest-with-babel)
+
+The following sections will go through how you can set up Jest with each of these options:
+
+### Quickstart
+
+You can use `create-next-app` with the [with-jest](https://github.com/vercel/next.js/tree/canary/examples/with-jest) example to quickly get started with Jest and React Testing Library:
+
+```bash
+npx create-next-app@latest --example with-jest with-jest-app
+```
+
+### Setting up Jest (with the Rust Compiler)
+
+Since the release of [Next.js 12](https://nextjs.org/blog/next-12), Next.js now has built-in configuration for Jest.
+
+To set up Jest, install `jest`, `jest-environment-jsdom`, `@testing-library/react`, `@testing-library/jest-dom`:
+
+```bash
+npm install --save-dev jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom
+```
+
+Create a `jest.config.js` file in your project's root directory and add the following:
+
+```jsx
+// jest.config.js
+const nextJest = require('next/jest')
+
+const createJestConfig = nextJest({
+ // Provide the path to your Next.js app to load next.config.js and .env files in your test environment
+ dir: './',
+})
+
+// Add any custom config to be passed to Jest
+/** @type {import('jest').Config} */
+const customJestConfig = {
+ // Add more setup options before each test is run
+ // setupFilesAfterEnv: ['/jest.setup.js'],
+ // if using TypeScript with a baseUrl set to the root directory then you need the below for alias' to work
+ moduleDirectories: ['node_modules', '/'],
+ testEnvironment: 'jest-environment-jsdom',
+}
+
+// createJestConfig is exported this way to ensure that next/jest can load the Next.js config which is async
+module.exports = createJestConfig(customJestConfig)
+```
+
+Under the hood, `next/jest` is automatically configuring Jest for you, including:
+
+- Setting up `transform` using [SWC](https://nextjs.org/docs/advanced-features/compiler)
+- Auto mocking stylesheets (`.css`, `.module.css`, and their scss variants), image imports and [`@next/font`](https://nextjs.org/docs/basic-features/font-optimization)
+- Loading `.env` (and all variants) into `process.env`
+- Ignoring `node_modules` from test resolving and transforms
+- Ignoring `.next` from test resolving
+- Loading `next.config.js` for flags that enable SWC transforms
+
+> **Note**: To test environment variables directly, load them manually in a separate setup script or in your `jest.config.js` file. For more information, please see [Test Environment Variables](https://nextjs.org/docs/basic-features/environment-variables#test-environment-variables).
+
+### Setting up Jest (with Babel)
+
+If you opt out of the [Rust Compiler](https://nextjs.org/docs/advanced-features/compiler), you will need to manually configure Jest and install `babel-jest` and `identity-obj-proxy` in addition to the packages above.
+
+Here are the recommended options to configure Jest for Next.js:
+
+```jsx
+// jest.config.js
+module.exports = {
+ collectCoverage: true,
+ // on node 14.x coverage provider v8 offers good speed and more or less good report
+ coverageProvider: 'v8',
+ collectCoverageFrom: [
+ '**/*.{js,jsx,ts,tsx}',
+ '!**/*.d.ts',
+ '!**/node_modules/**',
+ '!/out/**',
+ '!/.next/**',
+ '!/*.config.js',
+ '!/coverage/**',
+ ],
+ moduleNameMapper: {
+ // Handle CSS imports (with CSS modules)
+ // https://jestjs.io/docs/webpack#mocking-css-modules
+ '^.+\\.module\\.(css|sass|scss)$': 'identity-obj-proxy',
+
+ // Handle CSS imports (without CSS modules)
+ '^.+\\.(css|sass|scss)$': '/__mocks__/styleMock.js',
+
+ // Handle image imports
+ // https://jestjs.io/docs/webpack#handling-static-assets
+ '^.+\\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$/i': `/__mocks__/fileMock.js`,
+
+ // Handle module aliases
+ '^@/components/(.*)$': '/components/$1',
+ },
+ // Add more setup options before each test is run
+ // setupFilesAfterEnv: ['/jest.setup.js'],
+ testPathIgnorePatterns: ['/node_modules/', '/.next/'],
+ testEnvironment: 'jsdom',
+ transform: {
+ // Use babel-jest to transpile tests with the next/babel preset
+ // https://jestjs.io/docs/configuration#transform-objectstring-pathtotransformer--pathtotransformer-object
+ '^.+\\.(js|jsx|ts|tsx)$': ['babel-jest', { presets: ['next/babel'] }],
+ },
+ transformIgnorePatterns: [
+ '/node_modules/',
+ '^.+\\.module\\.(css|sass|scss)$',
+ ],
+}
+```
+
+You can learn more about each configuration option in the [Jest docs](https://jestjs.io/docs/configuration).
+
+**Handling stylesheets and image imports**
+
+Stylesheets and images aren't used in the tests but importing them may cause errors, so they will need to be mocked. Create the mock files referenced in the configuration above - `fileMock.js` and `styleMock.js` - inside a `__mocks__` directory:
+
+```js
+// __mocks__/fileMock.js
+module.exports = {
+ src: '/img.jpg',
+ height: 24,
+ width: 24,
+ blurDataURL: 'data:image/png;base64,imagedata',
+}
+```
+
+```js
+// __mocks__/styleMock.js
+module.exports = {}
+```
+
+For more information on handling static assets, please refer to the [Jest Docs](https://jestjs.io/docs/webpack#handling-static-assets).
+
+**Optional: Extend Jest with custom matchers**
+
+`@testing-library/jest-dom` includes a set of convenient [custom matchers](https://github.com/testing-library/jest-dom#custom-matchers) such as `.toBeInTheDocument()` making it easier to write tests. You can import the custom matchers for every test by adding the following option to the Jest configuration file:
+
+```js
+// jest.config.js
+setupFilesAfterEnv: ['/jest.setup.js']
+```
+
+Then, inside `jest.setup.js`, add the following import:
+
+```jsx
+// jest.setup.js
+import '@testing-library/jest-dom/extend-expect'
+```
+
+If you need to add more setup options before each test, it's common to add them to the `jest.setup.js` file above.
+
+**Optional: Absolute Imports and Module Path Aliases**
+
+If your project is using [Module Path Aliases](https://nextjs.org/docs/advanced-features/module-path-aliases), you will need to configure Jest to resolve the imports by matching the paths option in the `jsconfig.json` file with the `moduleNameMapper` option in the `jest.config.js` file. For example:
+
+```json
+// tsconfig.json or jsconfig.json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "paths": {
+ "@/components/*": ["components/*"]
+ }
+ }
+}
+```
+
+```jsx
+// jest.config.js
+moduleNameMapper: {
+ '^@/components/(.*)$': '/components/$1',
+}
+```
+
+### Creating your tests:
+
+**Add a test script to package.json**
+
+Add the Jest executable in watch mode to the `package.json` scripts:
+
+```jsx
+"scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "start": "next start",
+ "test": "jest --watch"
+}
+```
+
+`jest --watch` will re-run tests when a file is changed. For more Jest CLI options, please refer to the [Jest Docs](https://jestjs.io/docs/cli#reference).
+
+**Create your first tests**
+
+Your project is now ready to run tests. Follow Jest's convention by adding tests to the `__tests__` folder in your project's root directory.
+
+For example, we can add a test to check if the `` component successfully renders a heading:
+
+```jsx
+// __tests__/index.test.jsx
+
+import { render, screen } from '@testing-library/react'
+import Home from '../pages/index'
+import '@testing-library/jest-dom'
+
+describe('Home', () => {
+ it('renders a heading', () => {
+ render()
+
+ const heading = screen.getByRole('heading', {
+ name: /welcome to next\.js!/i,
+ })
+
+ expect(heading).toBeInTheDocument()
+ })
+})
+```
+
+Optionally, add a [snapshot test](https://jestjs.io/docs/snapshot-testing) to keep track of any unexpected changes to your `` component:
+
+```jsx
+// __tests__/snapshot.js
+
+import { render } from '@testing-library/react'
+import Home from '../pages/index'
+
+it('renders homepage unchanged', () => {
+ const { container } = render()
+ expect(container).toMatchSnapshot()
+})
+```
+
+> **Note**: Test files should not be included inside the pages directory because any files inside the pages directory are considered routes.
+
+**Running your test suite**
+
+Run `npm run test` to run your test suite. After your tests pass or fail, you will notice a list of interactive Jest commands that will be helpful as you add more tests.
+
+For further reading, you may find these resources helpful:
+
+- [Jest Docs](https://jestjs.io/docs/getting-started)
+- [React Testing Library Docs](https://testing-library.com/docs/react-testing-library/intro/)
+- [Testing Playground](https://testing-playground.com/) - use good testing practices to match elements.
+
+## Community Packages and Examples
+
+The Next.js community has created packages and articles you may find helpful:
+
+- [next-router-mock](https://github.com/scottrippey/next-router-mock) for Storybook.
+- [Test Preview Vercel Deploys with Cypress](https://glebbahmutov.com/blog/develop-preview-test/) by Gleb Bahmutov.
+
+For more information on what to read next, we recommend:
+
+
+}
+```
+
+```js
+// pages/index.js
+// Note how `components/MyComponent` exists but `Mycomponent` without the capital `c` is imported
+import MyComponent from '../components/Mycomponent'
+```
+
+Incorrect casing will lead to build failures on case-sensitive environments like most Linux-based continuous integration and can cause issues with Fast Refresh.
+
+##### The module you're trying to import uses Node.js specific modules
+
+`getStaticProps`, `getStaticPaths`, and `getServerSideProps` allow for using modules that can only run in the Node.js environment. This allows you to do direct database queries or reading data from Redis to name a few examples.
+
+The tree shaking only runs on top level pages, so it can't be relied on in separate React components.
+
+You can verify the tree shaking on [next-code-elimination.vercel.app](https://next-code-elimination.vercel.app/).
+
+Example of correctly tree shaken code:
+
+```js
+// lib/redis.js
+import Redis from 'ioredis'
+
+const redis = new Redis(process.env.REDIS_URL)
+
+export default redis
+```
+
+```js
+// pages/index.js
+import redis from '../lib/redis'
+
+export async function getStaticProps() {
+ const message = await redis.get('message')
+ return {
+ message,
+ }
+}
+
+export default function Home({ message }) {
+ return
{message}
+}
+```
+
+Example of code that would break:
+
+```js
+// lib/redis.js
+import Redis from 'ioredis'
+
+const redis = new Redis(process.env.REDIS_URL)
+
+export default redis
+```
+
+```js
+// pages/index.js
+// Redis is a Node.js specific library that can't run in the browser
+// Trying to use it in code that runs on both Node.js and the browser will result in a module not found error for modules that ioredis relies on
+// If you run into such an error it's recommended to move the code to `getStaticProps` or `getServerSideProps` as those methods guarantee that the code is only run in Node.js.
+import redis from '../lib/redis'
+import { useEffect, useState } from 'react'
+
+export default function Home() {
+ const [message, setMessage] = useState()
+ useEffect(() => {
+ redis.get('message').then((result) => {
+ setMessage(result)
+ })
+ }, [])
+ return
{message}
+}
+```
+
+Example of code that would break:
+
+```js
+// lib/redis.js
+import Redis from 'ioredis'
+
+// Modules that hold Node.js-only code can't also export React components
+// Tree shaking of getStaticProps/getStaticPaths/getServerSideProps is ran only on page files
+const redis = new Redis(process.env.REDIS_URL)
+
+export function MyComponent() {
+ return
Hello
+}
+
+export default redis
+```
+
+```js
+// pages/index.js
+// In practice you'll want to refactor the `MyComponent` to be a separate file so that tree shaking ensures that specific import is not included for the browser compilation
+import redis, { MyComponent } from '../lib/redis'
+
+export async function getStaticProps() {
+ const message = await redis.get('message')
+ return {
+ message,
+ }
+}
+
+export default function Home() {
+ return
+}
+```
diff --git a/errors/multi-tabs.md b/errors/multi-tabs.md
index 9b3b832069824..bf4f3f3d4abe3 100644
--- a/errors/multi-tabs.md
+++ b/errors/multi-tabs.md
@@ -10,4 +10,3 @@ More info here: https://tools.ietf.org/html/rfc6202#section-5.1
- Don't have too many tabs open to the same Next.js site open in development in the same browser at the same time.
- If using Firefox you can increase this limit by navigating to `about:config` and setting `network.http.max-persistent-connections-per-server` to a higher number
-
diff --git a/errors/nested-middleware.md b/errors/nested-middleware.md
new file mode 100644
index 0000000000000..710ba41e044dd
--- /dev/null
+++ b/errors/nested-middleware.md
@@ -0,0 +1,30 @@
+# Nested Middleware
+
+#### Why This Error Occurred
+
+You are defining a Middleware file in a location different from `/middleware`, which is not allowed.
+
+While in beta, a Middleware file under specific pages would _only_ be executed when pages below its declaration were matched, allowing nesting Middleware files. Based on customer feedback, we have replaced this API with a single root Middleware.
+
+#### Possible Ways to Fix It
+
+Declare your Middleware in the root folder and use `NextRequest` parsed URL to define which path the Middleware should be executed for.
+
+For example, a Middleware at `pages/about/_middleware.ts` can move the logic to `/middleware.ts` in the root of your repository. Then, a conditional statement can be used to only run the Middleware when it matches the `about/*` path:
+
+```typescript
+// /middleware.ts
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+ if (request.nextUrl.pathname.startsWith('/about')) {
+ // This logic is only applied to /about
+ }
+
+ if (request.nextUrl.pathname.startsWith('/dashboard')) {
+ // This logic is only applied to /dashboard
+ }
+}
+```
+
+If you have more than one Middleware, you should combine them into a single file and model their execution depending on the incoming request.
diff --git a/errors/nested-reserved-page.md b/errors/nested-reserved-page.md
new file mode 100644
index 0000000000000..69e503effbfa3
--- /dev/null
+++ b/errors/nested-reserved-page.md
@@ -0,0 +1,15 @@
+# Nested Reserved Page
+
+#### Why This Error Occurred
+
+In your pages folder you nested a reserved page e.g. `_app`, `_error`, or `_document` which causes the page to not be used since they must be located directly under the pages folder.
+
+#### Possible Ways to Fix It
+
+Move the reserved pages directly under your pages folder so that they are picked up and used correctly.
+
+### Useful Links
+
+- [Custom `_app` Documentation](https://nextjs.org/docs/advanced-features/custom-app)
+- [Custom `_error` Documentation](https://nextjs.org/docs/advanced-features/custom-error-page)
+- [Custom `_document` Documentation](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/nested-styled-jsx-tags.md b/errors/nested-styled-jsx-tags.md
new file mode 100644
index 0000000000000..160a0f4809dc1
--- /dev/null
+++ b/errors/nested-styled-jsx-tags.md
@@ -0,0 +1,54 @@
+# Nested `
+
+
+
+)
+```
+
+**After**
+
+```jsx
+const Component = () => (
+
+
Hello world
+
+
+
+)
+```
+
+### Useful Links
+
+- [Built-In CSS-in-JS](https://nextjs.org/docs/basic-features/built-in-css-support#css-in-js)
+- [styled-jsx documentation](https://github.com/vercel/styled-jsx)
diff --git a/errors/next-config-error.md b/errors/next-config-error.md
new file mode 100644
index 0000000000000..e30b025177387
--- /dev/null
+++ b/errors/next-config-error.md
@@ -0,0 +1,16 @@
+# next.config.js Loading Error
+
+#### Why This Error Occurred
+
+When attempting to load your `next.config.js` or `next.config.mjs` file, an error occurred. This could be due to a syntax error or attempting to `require`/`import` a module that wasn't available.
+
+#### Possible Ways to Fix It
+
+See the error message in your terminal where you started `next` to see more context.
+
+> Note: This config file is not transpiled by Next.js, so only use features supported by your current Node.js version.
+
+### Useful Links
+
+- [next.config.js documentation](https://nextjs.org/docs/api-reference/next.config.js/introduction)
+- [Node.js version feature chart](https://node.green/)
diff --git a/errors/next-dynamic-modules.md b/errors/next-dynamic-modules.md
new file mode 100644
index 0000000000000..a5fa9a1c98bfb
--- /dev/null
+++ b/errors/next-dynamic-modules.md
@@ -0,0 +1,66 @@
+# `next/dynamic` has deprecated loading multiple modules at once
+
+#### Why This Error Occurred
+
+The ability to load multiple modules at once has been deprecated in `next/dynamic` to be closer to React's implementation (`React.lazy` and `Suspense`).
+
+Updating code that relies on this behavior is relatively straightforward! We've provided an example of a before/after to help you migrate your application:
+
+#### Possible Ways To Fix It
+
+Migrate to using separate dynamic calls for each module.
+
+Before
+
+```js
+import dynamic from 'next/dynamic'
+
+const HelloBundle = dynamic({
+ modules: () => {
+ const components = {
+ Hello1: () => import('../components/hello1').then((m) => m.default),
+ Hello2: () => import('../components/hello2').then((m) => m.default),
+ }
+
+ return components
+ },
+ render: (props, { Hello1, Hello2 }) => (
+
+ )
+}
+
+function DynamicBundle() {
+ return
+}
+
+export default DynamicBundle
+```
diff --git a/errors/next-export-no-build-id.md b/errors/next-export-no-build-id.md
new file mode 100644
index 0000000000000..affed88c30803
--- /dev/null
+++ b/errors/next-export-no-build-id.md
@@ -0,0 +1,10 @@
+# Could not find a production build
+
+#### Why This Error Occurred
+
+When running `next export` a production build is needed.
+
+#### Possible Ways to Fix It
+
+- Run `next build` to create a production build before running `next export`.
+- If your intention was to run the development server run `next dev` instead.
diff --git a/errors/next-export-serverless.md b/errors/next-export-serverless.md
index 56e7a1e5a07a0..f0224f770cda8 100644
--- a/errors/next-export-serverless.md
+++ b/errors/next-export-serverless.md
@@ -6,4 +6,4 @@ Next.js can only handle exporting when the `target` is set to `server` (this is
#### Possible Ways to Fix It
-Change `target` to `server`, run `next build`, then run `next export` again.
\ No newline at end of file
+Change `target` to `server`, run `next build`, then run `next export` again.
diff --git a/errors/next-head-count-missing.md b/errors/next-head-count-missing.md
new file mode 100644
index 0000000000000..40c040f319461
--- /dev/null
+++ b/errors/next-head-count-missing.md
@@ -0,0 +1,11 @@
+# `next-head-count` is missing
+
+#### Why This Error Occurred
+
+You have a custom `pages/_document.js` that doesn't have the components required for Next.js to render correctly.
+
+#### Possible Ways to Fix It
+
+Ensure that your `_document.js` is importing and rendering all of the [required components](https://nextjs.org/docs/advanced-features/custom-document).
+
+In this case you are most likely not rendering the `` component imported from `next/document`.
diff --git a/errors/next-image-missing-loader-width.md b/errors/next-image-missing-loader-width.md
new file mode 100644
index 0000000000000..0df5c6efa7124
--- /dev/null
+++ b/errors/next-image-missing-loader-width.md
@@ -0,0 +1,17 @@
+# Missing `width` in the URL Returned by the Loader Prop on `next/image`
+
+#### Why This Error Occurred
+
+The [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop on the `next/image` component allows you to override the built-in URL resolution with a custom implementation in order to support any 3rd party cloud provider that can perform Image Optimization.
+
+This error occurred because the provided `loader()` function did not use `width` in the returned URL string. This means that the image will likely not be resized and therefore degrade performance.
+
+#### Possible Ways to Fix It
+
+- Ensure your Image Optimization provider can resize images. Then use the `width` parameter from the [`loader()`](https://nextjs.org/docs/api-reference/next/image#loader) function to construct the correct URL string.
+- Add the [`unoptimized`](https://nextjs.org/docs/api-reference/next/image#unoptimized) prop.
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)
diff --git a/errors/next-image-missing-loader.md b/errors/next-image-missing-loader.md
new file mode 100644
index 0000000000000..9a03dcb26a3d9
--- /dev/null
+++ b/errors/next-image-missing-loader.md
@@ -0,0 +1,15 @@
+# Missing `loader` Prop on `next/image`
+
+#### Why This Error Occurred
+
+When using the `next/image` component with [`loader="custom"`](https://nextjs.org/docs/basic-features/image-optimization#loader) in `next.config.js`, you must provide the [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop to the component with your custom implementation.
+
+#### Possible Ways to Fix It
+
+- Add the [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop to all usages of the `next/image` component.
+- Change the [`loader`](https://nextjs.org/docs/basic-features/image-optimization#loader) configuration in `next.config.js`.
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)
diff --git a/errors/next-image-unconfigured-host.md b/errors/next-image-unconfigured-host.md
new file mode 100644
index 0000000000000..fa23ec7af92e8
--- /dev/null
+++ b/errors/next-image-unconfigured-host.md
@@ -0,0 +1,41 @@
+# next/image Un-configured Host
+
+#### Why This Error Occurred
+
+One of your pages that leverages the `next/image` component, passed a `src` value that uses a hostname in the URL that isn't defined in the `images.remotePatterns` or `images.domains` in `next.config.js`.
+
+#### Possible Ways to Fix It
+
+Add the protocol, hostname, port, and pathname to the `images.remotePatterns` config in `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+ images: {
+ remotePatterns: [
+ {
+ protocol: 'https',
+ hostname: 'example.com',
+ port: '',
+ pathname: '/account123/**',
+ },
+ ],
+ },
+}
+```
+
+If you are using an older version of Next.js prior to 12.3.0, you can use `images.domains` instead:
+
+```js
+// next.config.js
+module.exports = {
+ images: {
+ domains: ['assets.example.com'],
+ },
+}
+```
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [Remote Patterns Documentation](https://nextjs.org/docs/api-reference/next/image#remote-patterns)
diff --git a/errors/next-image-upgrade-to-13.md b/errors/next-image-upgrade-to-13.md
new file mode 100644
index 0000000000000..3553cc3e3a401
--- /dev/null
+++ b/errors/next-image-upgrade-to-13.md
@@ -0,0 +1,40 @@
+# `next/image` changed in version 13
+
+#### Why This Error Occurred
+
+Starting in Next.js 13, the `next/image` component has undergone some major changes.
+
+Compared to the legacy component, the new `next/image` component has the following changes:
+
+- Removes `` wrapper around `` in favor of [native computed aspect ratio](https://caniuse.com/mdn-html_elements_img_aspect_ratio_computed_from_attributes)
+- Adds support for canonical `style` prop
+ - Removes `layout` prop in favor of `style` or `className`
+ - Removes `objectFit` prop in favor of `style` or `className`
+ - Removes `objectPosition` prop in favor of `style` or `className`
+- Removes `IntersectionObserver` implementation in favor of [native lazy loading](https://caniuse.com/loading-lazy-attr)
+ - Removes `lazyBoundary` prop since there is no native equivalent
+ - Removes `lazyRoot` prop since there is no native equivalent
+- Removes `loader` config in favor of [`loader`](#loader) prop
+- Changed `alt` prop from optional to required
+
+#### Possible Ways to Fix It
+
+Run the [next-image-to-legacy-image](https://nextjs.org/docs/advanced-features/codemods#next-image-to-legacy-image) codemod to automatically change `next/image` imports to `next/legacy/image`, for example:
+
+```
+npx @next/codemod next-image-to-legacy-image .
+```
+
+After running this codemod, you can optionally upgrade `next/legacy/image` to the new `next/image` with another codemod, for example:
+
+```
+npx @next/codemod next-image-experimental .
+```
+
+Please note this second codemod is experimental and only covers static usage (such as ``) but not dynamic usage (such as ``).
+
+### Useful Links
+
+- [Next.js 13 Blog Post](https://nextjs.org/blog/next-13)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)
+- [`next/legacy/image` Documentation](https://nextjs.org/docs/api-reference/next/legacy/image)
diff --git a/errors/next-router-not-mounted.md b/errors/next-router-not-mounted.md
new file mode 100644
index 0000000000000..0bdb3f7a9ce73
--- /dev/null
+++ b/errors/next-router-not-mounted.md
@@ -0,0 +1,13 @@
+# NextRouter was not mounted
+
+#### Why This Error Occurred
+
+A component used `useRouter` outside a Next.js application, or was rendered outside a Next.js application. This can happen when doing unit testing on components that use the `useRouter` hook as they are not configured with Next.js' contexts.
+
+#### Possible Ways to Fix It
+
+If used in a test, mock out the router by mocking the `next/router`'s `useRouter()` hook.
+
+### Useful Links
+
+- [next-router-mock](https://www.npmjs.com/package/next-router-mock)
diff --git a/errors/next-script-for-ga.md b/errors/next-script-for-ga.md
new file mode 100644
index 0000000000000..4dda57e70d1f5
--- /dev/null
+++ b/errors/next-script-for-ga.md
@@ -0,0 +1,100 @@
+# Next Script for Google Analytics
+
+> Prefer `next/script` component when using the inline script for Google Analytics.
+
+### Why This Error Occurred
+
+An inline script was used for Google analytics which might impact your webpage's performance.
+
+### Possible Ways to Fix It
+
+#### Using gtag.js
+
+If you are using the [gtag.js](https://developers.google.com/analytics/devguides/collection/gtagjs) script to add analytics, use the `next/script` component with the right loading strategy to defer loading of the script until necessary.
+
+```jsx
+import Script from 'next/script'
+
+function Home() {
+ return (
+
+
+
+
+
+ )
+}
+
+export default Home
+```
+
+#### Using analytics.js
+
+If you are using the [analytics.js](https://developers.google.com/analytics/devguides/collection/analyticsjs) script to add analytics:
+
+```jsx
+import Script from 'next/script'
+
+function Home() {
+ return (
+
+
+
+ )
+}
+
+export default Home
+```
+
+If you are using the [alternative async variant](https://developers.google.com/analytics/devguides/collection/analyticsjs#alternative_async_tag):
+
+```jsx
+import Script from 'next/script'
+
+function Home() {
+ return (
+
+
+
+
+ )
+}
+
+export default Home
+```
+
+### Useful Links
+
+- [Add analytics.js to Your Site](https://developers.google.com/analytics/devguides/collection/analyticsjs)
+- [Efficiently load third-party JavaScript](https://web.dev/efficiently-load-third-party-javascript/)
+- [next/script Documentation](https://nextjs.org/docs/basic-features/script)
diff --git a/errors/next-start-serverless.md b/errors/next-start-serverless.md
index 483f024d99d4c..86009d133d7ea 100644
--- a/errors/next-start-serverless.md
+++ b/errors/next-start-serverless.md
@@ -6,4 +6,4 @@ Next.js can only handle running a server when the `target` is set to `server` (t
#### Possible Ways to Fix It
-Use a different handler than `next start` when testing a serverless **production** build, otherwise just use `next dev`.
+Use a different handler than `next start` when testing a serverless **production** build, otherwise use `next dev`.
diff --git a/errors/no-assign-module-variable.md b/errors/no-assign-module-variable.md
new file mode 100644
index 0000000000000..caf4d2d769a0d
--- /dev/null
+++ b/errors/no-assign-module-variable.md
@@ -0,0 +1,15 @@
+# No assign module variable
+
+> Prevent assignment to the `module` variable.
+
+#### Why This Error Occurred
+
+A value is being assigned to the `module` variable. The `module` variable is already used and it is highly likely that assigning to this variable will cause errors.
+
+#### Possible Ways to Fix It
+
+Use a different variable name:
+
+```js
+let myModule = {...}
+```
diff --git a/errors/no-before-interactive-script-outside-document.md b/errors/no-before-interactive-script-outside-document.md
new file mode 100644
index 0000000000000..e40c3f67129c0
--- /dev/null
+++ b/errors/no-before-interactive-script-outside-document.md
@@ -0,0 +1,35 @@
+# No Before Interactive Script Outside Document
+
+> Prevent usage of `next/script`'s `beforeInteractive` strategy outside of `pages/_document.js`.
+
+#### Why This Error Occurred
+
+You cannot use the `next/script` component with the `beforeInteractive` strategy outside `pages/_document.js`. That's because `beforeInteractive` strategy only works inside **`pages/_document.js`** and is designed to load scripts that are needed by the entire site (i.e. the script will load when any page in the application has been loaded server-side).
+
+#### Possible Ways to Fix It
+
+If you want a global script, move the script inside `pages/_document.js`.
+
+```jsx
+// In `pages/_document.js`
+import { Html, Head, Main, NextScript } from 'next/document'
+import Script from 'next/script'
+
+export default function Document() {
+ return (
+
+
+
+
+
+
+
+
+ )
+}
+```
+
+- [next-script](https://nextjs.org/docs/basic-features/script#usage)
diff --git a/errors/no-cache.md b/errors/no-cache.md
new file mode 100644
index 0000000000000..4e4b9963d9227
--- /dev/null
+++ b/errors/no-cache.md
@@ -0,0 +1,14 @@
+# No Cache Detected
+
+### Why This Error Occurred
+
+A Next.js build was triggered in a continuous integration environment, but no cache was detected.
+
+This results in slower builds and can hurt Next.js' persistent caching of client-side bundles across builds.
+
+### Possible Ways to Fix It
+
+> **Note**: If this is a new project, or being built for the first time in your CI, you can ignore this error.
+> However, you'll want to make sure it doesn't continue to happen and fix it if it does!
+
+Follow the instructions in [CI Build Caching](https://nextjs.org/docs/advanced-features/ci-build-caching) to ensure your Next.js cache is persisted between builds.
diff --git a/errors/no-css-tags.md b/errors/no-css-tags.md
new file mode 100644
index 0000000000000..c9926b25b81f1
--- /dev/null
+++ b/errors/no-css-tags.md
@@ -0,0 +1,40 @@
+# No CSS Tags
+
+> Prevent manual stylesheet tags.
+
+### Why This Error Occurred
+
+A `link` element was used to link to an external stylesheet. This can negatively affect CSS resource loading on your webpage.
+
+### Possible Ways to Fix It
+
+There are multiple ways to include styles using Next.js' built-in CSS support, including the option to use `@import` within the root stylesheet that is imported in `pages/_app.js`:
+
+```css
+/* Root stylesheet */
+@import 'extra.css';
+
+body {
+ /* ... */
+}
+```
+
+Another option is to use CSS Modules to import the CSS file scoped specifically to the component.
+
+```jsx
+import styles from './extra.module.css'
+
+export class Home {
+ render() {
+ return (
+
+
+
+ )
+ }
+}
+```
+
+Refer to the [Built-In CSS Support](https://nextjs.org/docs/basic-features/built-in-css-support) documentation to learn about all the ways to include CSS to your application.
diff --git a/errors/no-document-import-in-page.md b/errors/no-document-import-in-page.md
new file mode 100644
index 0000000000000..bb2713856f9a6
--- /dev/null
+++ b/errors/no-document-import-in-page.md
@@ -0,0 +1,26 @@
+# No Document Import in Page
+
+> Prevent importing `next/document` outside of `pages/_document.js`.
+
+### Why This Error Occurred
+
+`next/document` was imported in a page outside of `pages/_document.js` (or `pages/_document.tsx` if you are using TypeScript). This can cause unexpected issues in your application.
+
+### Possible Ways to Fix It
+
+Only import and use `next/document` within `pages/_document.js` (or `pages/_document.tsx`) to override the default `Document` component:
+
+```jsx
+// pages/_document.js
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+ //...
+}
+
+export default MyDocument
+```
+
+### Useful Links
+
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/no-document-title.md b/errors/no-document-title.md
index c71b6d5f6d007..e83b856defe92 100644
--- a/errors/no-document-title.md
+++ b/errors/no-document-title.md
@@ -1,4 +1,4 @@
-# `` should not be used in _document.js's `<Head>`
+# `<title>` should not be used in \_document.js's `<Head>`
#### Why This Error Occurred
@@ -10,37 +10,23 @@ Set `<title>` in `pages/_app.js` instead:
```js
// pages/_app.js
-import App, {Container} from 'next/app'
-import Head from 'next/head'
import React from 'react'
+import Head from 'next/head'
-export default class MyApp extends App {
- static async getInitialProps ({ Component, ctx }) {
- let pageProps = {}
-
- if (Component.getInitialProps) {
- pageProps = await Component.getInitialProps(ctx)
- }
-
- return { pageProps }
- }
-
- render () {
- const { Component, pageProps } = this.props
-
- return (
- <Container>
- <Head>
- <title>My new cool app
-
-
-
- )
- }
+function MyApp({ Component, pageProps }) {
+ return (
+ <>
+
+ My new cool app
+
+
+
+ )
}
-```
+export default MyApp
+```
### Useful Links
-- [The issue this was reported in: #4596](https://github.com/zeit/next.js/issues/4596)
+- [The issue this was reported in: #4596](https://github.com/vercel/next.js/issues/4596)
diff --git a/errors/no-document-viewport-meta.md b/errors/no-document-viewport-meta.md
new file mode 100644
index 0000000000000..bf5131b348a24
--- /dev/null
+++ b/errors/no-document-viewport-meta.md
@@ -0,0 +1,32 @@
+# Viewport `meta` tags should not be used in `_document.js`'s ``
+
+#### Why This Error Occurred
+
+Adding `` in `pages/_document.js` will lead to unexpected results since it cannot be deduped.
+The viewport tag should be handled by `next/head` in `pages/_app.js`.
+
+#### Possible Ways to Fix It
+
+Set your viewport `meta` tag in `pages/_app.js` instead:
+
+```tsx
+// pages/_app.js
+import Head from 'next/head'
+
+function MyApp({ Component, pageProps }) {
+ return (
+ <>
+
+
+
+
+
+ )
+}
+
+export default MyApp
+```
+
+### Useful Links
+
+- [Issue #13230](https://github.com/vercel/next.js/issues/13230), which led to the creation of this warning.
diff --git a/errors/no-duplicate-head.md b/errors/no-duplicate-head.md
new file mode 100644
index 0000000000000..4ba4314f18456
--- /dev/null
+++ b/errors/no-duplicate-head.md
@@ -0,0 +1,40 @@
+# No Duplicate Head
+
+> Prevent duplicate usage of `` in `pages/_document.js`.
+
+### Why This Error Occurred
+
+More than a single instance of the `` component was used in a single custom document. This can cause unexpected behavior in your application.
+
+### Possible Ways to Fix It
+
+Only use a single `` component in your custom document in `pages/_document.js`.
+
+```jsx
+// pages/_document.js
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+ static async getInitialProps(ctx) {
+ //...
+ }
+
+ render() {
+ return (
+
+
+
+
+
+
+
+ )
+ }
+}
+
+export default MyDocument
+```
+
+### Useful Links
+
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/no-head-element.md b/errors/no-head-element.md
new file mode 100644
index 0000000000000..f3bd5ca349270
--- /dev/null
+++ b/errors/no-head-element.md
@@ -0,0 +1,32 @@
+# No Head Element
+
+> Prevent usage of `` element.
+
+### Why This Error Occurred
+
+A `` element was used to include page-level metadata, but this can cause unexpected behavior in a Next.js application. Use Next.js' built-in `next/head` component instead.
+
+### Possible Ways to Fix It
+
+Import and use the `` component:
+
+```jsx
+import Head from 'next/head'
+
+function Index() {
+ return (
+ <>
+
+ My page title
+
+
+
+ )
+}
+
+export default Index
+```
+
+### Useful Links
+
+- [next/head](https://nextjs.org/docs/api-reference/next/head)
diff --git a/errors/no-head-import-in-document.md b/errors/no-head-import-in-document.md
new file mode 100644
index 0000000000000..cb9c18e08eb88
--- /dev/null
+++ b/errors/no-head-import-in-document.md
@@ -0,0 +1,36 @@
+# No Head Import in Document
+
+> Prevent usage of `next/head` in `pages/_document.js`.
+
+### Why This Error Occurred
+
+`next/head` was imported in `pages/_document.js`. This can cause unexpected issues in your application.
+
+### Possible Ways to Fix It
+
+Only import and use `next/document` within `pages/_document.js` to override the default `Document` component. If you are importing `next/head` to use the `Head` component, import it from `next/document` instead in order to modify `` code across all pages:
+
+```jsx
+// pages/_document.js
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+ static async getInitialProps(ctx) {
+ //...
+ }
+
+ render() {
+ return (
+
+
+
+ )
+ }
+}
+
+export default MyDocument
+```
+
+### Useful Links
+
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/no-html-link-for-pages.md b/errors/no-html-link-for-pages.md
new file mode 100644
index 0000000000000..32e124dc11fda
--- /dev/null
+++ b/errors/no-html-link-for-pages.md
@@ -0,0 +1,65 @@
+# No HTML link for pages
+
+> Prevent usage of `` elements to navigate to internal Next.js pages.
+
+### Why This Error Occurred
+
+An `` element was used to navigate to a page route without using the `next/link` component, causing unnecessary full page refreshes.
+
+The `Link` component is required in order to enable client-side route transitions between pages and provide a single-page app experience.
+
+### Possible Ways to Fix It
+
+Make sure to import the `Link` component and wrap anchor elements that route to different page routes.
+
+**Before:**
+
+```jsx
+function Home() {
+ return (
+
+ )
+}
+
+export default Home
+```
+
+### Options
+
+#### `pagesDir`
+
+This rule can normally locate your `pages` directory automatically.
+
+If you're working in a monorepo, we recommend configuring the [`rootDir`](/docs/basic-features/eslint.md#rootDir) setting in `eslint-plugin-next`, which `pagesDir` will use to locate your `pages` directory.
+
+In some cases, you may also need to configure this rule directly by providing a `pages` directory. This can be a path or an array of paths.
+
+```json
+{
+ "rules": {
+ "@next/next/no-html-link-for-pages": ["error", "packages/my-app/pages/"]
+ }
+}
+```
+
+### Useful Links
+
+- [next/link API Reference](https://nextjs.org/docs/api-reference/next/link)
diff --git a/errors/no-img-element.md b/errors/no-img-element.md
new file mode 100644
index 0000000000000..1e4d9f651442a
--- /dev/null
+++ b/errors/no-img-element.md
@@ -0,0 +1,51 @@
+# No Img Element
+
+> Prevent usage of `` element to prevent layout shift.
+
+### Why This Error Occurred
+
+An `` element was used to display an image. Use either `` in conjunction with `` element, or use `next/image` that has better performance and automatic Image Optimization over ``.
+
+### Possible Ways to Fix It
+
+Import and use the `` component:
+
+```jsx
+import Image from 'next/image'
+
+function Home() {
+ return (
+ <>
+
+
+ )
+}
+
+export default Home
+```
+
+
+
+Use `` in conjunction with `` element:
+
+```jsx
+function Home() {
+ return (
+ <>
+
+
+
+
+
+ )
+}
+```
+
+### Useful Links
+
+- [Image Component and Image Optimization](https://nextjs.org/docs/basic-features/image-optimization)
diff --git a/errors/no-on-app-updated-hook.md b/errors/no-on-app-updated-hook.md
index ec0e0524f88fe..5437cef9d4f71 100644
--- a/errors/no-on-app-updated-hook.md
+++ b/errors/no-on-app-updated-hook.md
@@ -1,11 +1,11 @@
# Router.onAppUpdated is removed
-Due to [this bug fix](https://github.com/zeit/next.js/pull/3849), we had to remove the `Router.onAppUpdated` hook. But the default functionality of this feature is still in effect.
+Due to [this bug fix](https://github.com/vercel/next.js/pull/3849), we had to remove the `Router.onAppUpdated` hook. But the default functionality of this feature is still in effect.
We use this hook to detect a new app deployment when switching pages and act accordingly. Although there are many things you can do in this hook, it's often used to navigate the page via the server as shown below:
```js
-Router.onAppUpdated = function(nextRoute) {
+Router.onAppUpdated = function (nextRoute) {
location.href = nextRoute
}
```
@@ -17,9 +17,9 @@ One real use of this hook is to persist your application state to local-storage
This is code for that:
```js
-window.onbeforeunload = function(e) {
+window.onbeforeunload = function (e) {
// Get the application state (usually from a store like Redux)
const appState = {}
- localStorage.setItem('app-state', JSON.stringify(appState));
-};
+ localStorage.setItem('app-state', JSON.stringify(appState))
+}
```
diff --git a/errors/no-page-custom-font.md b/errors/no-page-custom-font.md
new file mode 100644
index 0000000000000..2f2e51e3d28e5
--- /dev/null
+++ b/errors/no-page-custom-font.md
@@ -0,0 +1,73 @@
+# No Page Custom Font
+
+> Prevent page-only custom fonts.
+
+### Why This Error Occurred
+
+- The custom font you're adding was added to a page - this only adds the font to the specific page and not the entire application.
+- The custom font you're adding was added to a separate component within `pages/_document.js` - this disables automatic font optimization.
+
+### Possible Ways to Fix It
+
+Create the file `./pages/_document.js` and add the font to a custom Document:
+
+```jsx
+// pages/_document.js
+
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+ render() {
+ return (
+
+
+
+
+
+
+
+
+
+ )
+ }
+}
+
+export default MyDocument
+```
+
+Or as a function component:
+
+```js
+// pages/_document.js
+
+import { Html, Head, Main, NextScript } from 'next/document'
+
+export default function Document() {
+ return (
+
+
+
+
+
+
+
+
+
+ )
+}
+```
+
+### When Not To Use It
+
+If you have a reason to only load a font for a particular page or don't care about font optimization, then you can disable this rule.
+
+### Useful Links
+
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
+- [Font Optimization](https://nextjs.org/docs/basic-features/font-optimization)
diff --git a/errors/no-router-instance.md b/errors/no-router-instance.md
index 2381b0e72d6d1..2beaafbc71cbb 100644
--- a/errors/no-router-instance.md
+++ b/errors/no-router-instance.md
@@ -2,8 +2,12 @@
#### Why This Error Occurred
-During SSR you might have tried to access a router method `push`, `replace`, `back`, which is not supported.
+During Pre-rendering (SSR or SSG) you tried to access a router method `push`, `replace`, `back`, which is not supported.
#### Possible Ways to Fix It
-Move any calls to router methods to `componentDidMount` or add a check such as `typeof window !== 'undefined'` before calling the methods
\ No newline at end of file
+In a function Component you can move the code into the `useEffect` hook.
+
+In a class Component, move any calls to router methods to the `componentDidMount` lifecycle method.
+
+This way the calls to the router methods are only executed in the browser.
diff --git a/errors/no-script-component-in-head.md b/errors/no-script-component-in-head.md
new file mode 100644
index 0000000000000..50503ebe0eaec
--- /dev/null
+++ b/errors/no-script-component-in-head.md
@@ -0,0 +1,50 @@
+# No Script Component in Head
+
+> Prevent usage of `next/script` in `next/head` component.
+
+#### Why This Error Occurred
+
+The `next/script` component should not be used in a `next/head` component.
+
+#### Possible Ways to Fix It
+
+Move the `` component outside of `` instead.
+
+**Before**
+
+```js
+import Script from 'next/script'
+import Head from 'next/head'
+
+export default function Index() {
+ return (
+
+ Next.js
+
+
+ )
+}
+```
+
+**After**
+
+```js
+import Script from 'next/script'
+import Head from 'next/head'
+
+export default function Index() {
+ return (
+ <>
+
+ Next.js
+
+
+
+ )
+}
+```
+
+### Useful links
+
+- [next/head](https://nextjs.org/docs/api-reference/next/head)
+- [next/script](https://nextjs.org/docs/basic-features/script#usage)
diff --git a/errors/no-script-in-document.md b/errors/no-script-in-document.md
new file mode 100644
index 0000000000000..6920e464cfe26
--- /dev/null
+++ b/errors/no-script-in-document.md
@@ -0,0 +1,31 @@
+# No Script in Document
+
+> Prevent usage of `next/script` in `pages/_document.js`.
+
+> ⚠️ This error is not relevant in Next.js versions 12.1.6 or later. Please refer to the updated [error message](https://nextjs.org/docs/messages/no-before-interactive-script-outside-document).
+
+#### Why This Error Occurred
+
+You should not use the `next/script` component in `pages/_document.js` in Next.js versions prior to 12.1.6. That's because the `pages/_document.js` page only runs on the server and `next/script` has client-side functionality to ensure loading order.
+
+#### Possible Ways to Fix It
+
+If you want a global script, use `next/script` in `pages/_app.js` instead.
+
+```jsx
+import Script from 'next/script'
+
+function MyApp({ Component, pageProps }) {
+ return (
+ <>
+
+
+
+ )
+}
+
+export default MyApp
+```
+
+- [custom-app](https://nextjs.org/docs/advanced-features/custom-app)
+- [next-script](https://nextjs.org/docs/basic-features/script#usage)
diff --git a/errors/no-script-tags-in-head-component.md b/errors/no-script-tags-in-head-component.md
new file mode 100644
index 0000000000000..974e2b9248146
--- /dev/null
+++ b/errors/no-script-tags-in-head-component.md
@@ -0,0 +1,30 @@
+# No Script Tags In Head Component
+
+### Why This Error Occurred
+
+A `
+
Home Page
+
+ )
+}
+
+export default Home
+```
+
+#### Use `async` or `defer`
+
+```html
+
+
+```
+
+### Useful Links
+
+- [Efficiently load third-party JavaScript](https://web.dev/efficiently-load-third-party-javascript/)
diff --git a/errors/no-title-in-document-head.md b/errors/no-title-in-document-head.md
new file mode 100644
index 0000000000000..3b8ab77dd9ca1
--- /dev/null
+++ b/errors/no-title-in-document-head.md
@@ -0,0 +1,30 @@
+# No Title in Document Head
+
+> Prevent usage of `` with `Head` component from `next/document`.
+
+### Why This Error Occurred
+
+A `<title>` element was defined within the `Head` component imported from `next/document`, which should only be used for any `<head>` code that is common for all pages. Title tags should be defined at the page-level using `next/head` instead.
+
+### Possible Ways to Fix It
+
+Within a page or component, import and use `next/head` to define a page title:
+
+```jsx
+import Head from 'next/head'
+
+export function Home() {
+ return (
+ <div>
+ <Head>
+ <title>My page title
+
+
+ )
+}
+```
+
+### Useful links
+
+- [next/head](https://nextjs.org/docs/api-reference/next/head)
+- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
diff --git a/errors/no-unwanted-polyfillio.md b/errors/no-unwanted-polyfillio.md
new file mode 100644
index 0000000000000..9d00cbc8579fd
--- /dev/null
+++ b/errors/no-unwanted-polyfillio.md
@@ -0,0 +1,15 @@
+# No Unwanted Polyfill.io
+
+> Prevent duplicate polyfills from Polyfill.io.
+
+#### Why This Error Occurred
+
+You are using polyfills from Polyfill.io and including polyfills already shipped with Next.js. This unnecessarily increases page weight which can affect loading performance.
+
+#### Possible Ways to Fix It
+
+Remove all duplicate polyfills. If you need to add polyfills but are not sure if Next.js already includes it, take a look at the list of [supported browsers and features](https://nextjs.org/docs/basic-features/supported-browsers-features).
+
+### Useful Links
+
+- [Supported Browsers and Features](https://nextjs.org/docs/basic-features/supported-browsers-features)
diff --git a/errors/node-module-in-edge-runtime.md b/errors/node-module-in-edge-runtime.md
new file mode 100644
index 0000000000000..ea128326a41b9
--- /dev/null
+++ b/errors/node-module-in-edge-runtime.md
@@ -0,0 +1,18 @@
+# Using Node.js Modules in Edge Runtime
+
+#### Why This Error Occurred
+
+The code in your [Middleware](https://nextjs.org/docs/advanced-features/middleware) or your [Edge API Routes](https://nextjs.org/docs/api-routes/edge-api-routes) is using a feature from Node.js runtime.
+
+However, the Edge Runtime does not support [Node.js APIs and globals](https://nextjs.org/docs/api-reference/edge-runtime#unsupported-apis).
+
+#### Possible Ways to Fix It
+
+When running Next.js locally with `next dev`, your application will show in the console, and in your browser, which file is importing and using an unsupported module. This module must be avoided: either by not importing it, or by replacing it with a polyfill.
+
+For example, you might replace the Node.js `crypto` module with the [Web Crypto API](<[https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API](https://nextjs.org/docs/api-reference/edge-runtime#web-crypto-apis)>).
+
+### Useful Links
+
+- [Edge Runtime Supported APIs](https://nextjs.org/docs/api-reference/edge-runtime)
+- [Next.js Middleware](https://nextjs.org/docs/advanced-features/middleware)
diff --git a/errors/non-dynamic-getstaticpaths-usage.md b/errors/non-dynamic-getstaticpaths-usage.md
new file mode 100644
index 0000000000000..2f94c774b0cab
--- /dev/null
+++ b/errors/non-dynamic-getstaticpaths-usage.md
@@ -0,0 +1,14 @@
+# getStaticPaths Used on Non-Dynamic Page
+
+#### Why This Error Occurred
+
+On a non-dynamic SSG page `getStaticPaths` was incorrectly exported as this can only be used on dynamic pages to return the paths to prerender.
+
+#### Possible Ways to Fix It
+
+Remove the `getStaticPaths` export on the non-dynamic page or rename the page to be a dynamic page.
+
+### Useful Links
+
+- [Dynamic Routes Documentation](https://nextjs.org/docs/routing/dynamic-routes)
+- [`getStaticPaths` Documentation](https://nextjs.org/docs/routing/dynamic-routes)
diff --git a/errors/non-standard-node-env.md b/errors/non-standard-node-env.md
new file mode 100644
index 0000000000000..238823e622dd1
--- /dev/null
+++ b/errors/non-standard-node-env.md
@@ -0,0 +1,29 @@
+# Non-Standard NODE_ENV
+
+#### Why This Error Occurred
+
+Your environment has a non-standard `NODE_ENV` value configured.
+
+This may be by accident, so if you're unaware where the value is coming from, check the following:
+
+- The `.env*` files in your project, if present
+- Your `~/.bash_profile`, if present
+- Your `~/.zshrc`, if present
+
+The greater React ecosystem treats `NODE_ENV` as a convention, only permitting three (3) values:
+
+- `production`: When your application is built with `next build`
+- `development`: When your application is ran with `next dev`
+- `test`: When your application is being tested (e.g. `jest`)
+
+Setting a non-standard `NODE_ENV` value may cause dependencies to behave unexpectedly, or worse, **break dead code elimination**.
+
+#### Possible Ways to Fix It
+
+To fix this error, identify the source of the erroneous `NODE_ENV` value and get rid of it: Next.js automatically sets the correct value for you.
+
+If you need the concept of different environments in your application, e.g. `staging`, you should use a different environment variable name like `APP_ENV`.
+
+### Useful Links
+
+- [Environment Variables](https://en.wikipedia.org/wiki/Environment_variable)
diff --git a/errors/nonce-contained-invalid-characters.md b/errors/nonce-contained-invalid-characters.md
new file mode 100644
index 0000000000000..3befd0651f9f0
--- /dev/null
+++ b/errors/nonce-contained-invalid-characters.md
@@ -0,0 +1,20 @@
+# nonce contained invalid characters
+
+#### Why This Error Occurred
+
+This happens when there is a request that contains a `Content-Security-Policy`
+header that contains a `script-src` directive with a nonce value that contains
+invalid characters (any one of `<>&` characters). For example:
+
+- `'nonce-'`: not allowed
+- `'nonce-/>script<>'`: not allowed
+- `'nonce-PHNjcmlwdCAvPg=='`: allowed
+- `'nonce-Lz5zY3JpcHQ8Pg=='`: allowed
+
+#### Possible Ways to Fix It
+
+Replace the nonce value with a base64 encoded value.
+
+### Useful Links
+
+- [Content Security Policy Sources](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources)
diff --git a/errors/opening-an-issue.md b/errors/opening-an-issue.md
new file mode 100644
index 0000000000000..34a08b391843a
--- /dev/null
+++ b/errors/opening-an-issue.md
@@ -0,0 +1,28 @@
+# Opening a new Issue
+
+#### Why This Message Occurred
+
+When `next info` was run, Next.js detected that it's was not on the latest canary release.
+
+`next@canary` is the canary version of Next.js that ships daily. It includes all features and fixes that have not been released to the stable version yet. Think of canary as a public beta.
+
+Some issues may already be fixed in the canary version, so please verify that your issue reproduces before opening a new issue.
+
+Run the following in the codebase:
+
+```bash
+npm install next@canary
+```
+
+or
+
+```bash
+yarn add next@canary
+```
+
+And go through the prepared reproduction steps once again, and check if the issue still exists.
+
+### Useful Links
+
+- [Video: How to Contribute to Open Source (Next.js)](https://www.youtube.com/watch?v=cuoNzXFLitc)
+- [Contributing to Next.js](https://github.com/vercel/next.js/blob/canary/contributing.md)
diff --git a/errors/opt-out-auto-static-optimization.md b/errors/opt-out-auto-static-optimization.md
new file mode 100644
index 0000000000000..4c2115e84b957
--- /dev/null
+++ b/errors/opt-out-auto-static-optimization.md
@@ -0,0 +1,37 @@
+# Opt-out of Automatic Static Optimization
+
+#### Why This Warning Occurred
+
+You are using `getInitialProps` in your [Custom ``](https://nextjs.org/docs/advanced-features/custom-app).
+
+This causes **all non-getStaticProps pages** to be executed on the server -- disabling [Automatic Static Optimization](https://nextjs.org/docs/advanced-features/automatic-static-optimization).
+
+#### Possible Ways to Fix It
+
+Be sure you meant to use `getInitialProps` in `pages/_app`!
+There are some valid use cases for this, but it is often better to handle `getInitialProps` on a _per-page_ basis.
+
+Check for any [higher-order components](https://reactjs.org/docs/higher-order-components.html) that may have added `getInitialProps` to your [Custom ``](https://nextjs.org/docs/advanced-features/custom-app).
+
+If you previously copied the [Custom ``](https://nextjs.org/docs/advanced-features/custom-app) example, you may be able to remove your `getInitialProps`.
+
+The following `getInitialProps` does nothing and may be removed:
+
+```js
+class MyApp extends App {
+ // Remove me, I do nothing!
+ static async getInitialProps({ Component, ctx }) {
+ let pageProps = {}
+
+ if (Component.getInitialProps) {
+ pageProps = await Component.getInitialProps(ctx)
+ }
+
+ return { pageProps }
+ }
+
+ render() {
+ // ...
+ }
+}
+```
diff --git a/errors/opt-out-automatic-prerendering.md b/errors/opt-out-automatic-prerendering.md
new file mode 100644
index 0000000000000..f3db86439cc7f
--- /dev/null
+++ b/errors/opt-out-automatic-prerendering.md
@@ -0,0 +1,35 @@
+# Opt-out of Automatic Static Optimization
+
+#### Why This Warning Occurred
+
+You are using `getInitialProps` in your [Custom ``](https://nextjs.org/docs/advanced-features/custom-app).
+
+This causes **all pages** to be executed on the server -- disabling [Automatic Static Optimization](https://nextjs.org/docs/advanced-features/automatic-static-optimization).
+
+#### Possible Ways to Fix It
+
+Be sure you meant to use `getInitialProps` in `pages/_app`!
+There are some valid use cases for this, but it is often better to handle `getInitialProps` on a _per-page_ basis.
+
+If you previously copied the [Custom ``](https://nextjs.org/docs/advanced-features/custom-app) example, you may be able to remove your `getInitialProps`.
+
+The following `getInitialProps` does nothing and may be removed:
+
+```js
+class MyApp extends App {
+ // Remove me, I do nothing!
+ static async getInitialProps({ Component, ctx }) {
+ let pageProps = {}
+
+ if (Component.getInitialProps) {
+ pageProps = await Component.getInitialProps(ctx)
+ }
+
+ return { pageProps }
+ }
+
+ render() {
+ // ...
+ }
+}
+```
diff --git a/errors/page-data-collection-timeout.md b/errors/page-data-collection-timeout.md
new file mode 100644
index 0000000000000..70539d20e88d7
--- /dev/null
+++ b/errors/page-data-collection-timeout.md
@@ -0,0 +1,19 @@
+# Collecting page data timed out after multiple attempts
+
+#### Why This Error Occurred
+
+Next.js tries to restart the worker pool of the page data collection when no progress happens for a while, to avoid hanging builds.
+
+When restarted it will retry all uncompleted jobs, but if a job was unsuccessfully attempted multiple times, this will lead to an error.
+
+#### Possible Ways to Fix It
+
+- Make sure that there is no infinite loop during execution.
+- Make sure all Promises in `getStaticPaths` `resolve` or `reject` correctly.
+- Avoid very long timeouts for network requests.
+- Increase the timeout by changing the `config.staticPageGenerationTimeout` configuration option (default `60` in seconds).
+
+### Useful Links
+
+- [`getStaticPaths`](https://nextjs.org/docs/basic-features/data-fetching/get-static-paths)
+- [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching/get-static-props)
diff --git a/errors/page-without-valid-component.md b/errors/page-without-valid-component.md
new file mode 100644
index 0000000000000..965bce9fdb6d6
--- /dev/null
+++ b/errors/page-without-valid-component.md
@@ -0,0 +1,18 @@
+# Page Without Valid React Component
+
+#### Why This Error Occurred
+
+A page that does not export a valid React Component was found while analyzing the build output.
+
+This is a hard error because the page would error when rendered, and causes poor build performance.
+
+#### Possible Ways to Fix It
+
+Investigate the list of page(s) specified in the error message.
+For each, you'll want to check if the file is meant to be a page.
+
+If the file is not meant to be a page, and instead, is a shared component or file, move the file to a different folder like `components` or `lib`.
+
+If the file is meant to be a page, double check you have an `export default` with the React Component instead of an `export`. If you're already using `export default`, make sure the returned value is a valid React Component.
+
+If you need to support a different file extension for a page component (such as `.mdx`) or would like to include non-page files in the `pages` directory, configure [Custom Page Extensions](https://nextjs.org/docs/api-reference/next.config.js/custom-page-extensions) in the `next.config.js`.
diff --git a/errors/placeholder-blur-data-url.md b/errors/placeholder-blur-data-url.md
new file mode 100644
index 0000000000000..9c9a76819dd78
--- /dev/null
+++ b/errors/placeholder-blur-data-url.md
@@ -0,0 +1,15 @@
+# `placeholder=blur` without `blurDataURL`
+
+#### Why This Error Occurred
+
+You are attempting use the `next/image` component with `placeholder=blur` property but no `blurDataURL` property.
+
+The `blurDataURL` might be missing because you're using a string for `src` instead of a static import.
+
+Or `blurDataURL` might be missing because the static import is an unsupported image format. Only jpg, png, webp, and avif are supported at this time.
+
+#### Possible Ways to Fix It
+
+- Add a [`blurDataURL`](https://nextjs.org/docs/api-reference/next/image#blurdataurl) property, the contents should be a small Data URL to represent the image
+- Change the [`src`](https://nextjs.org/docs/api-reference/next/image#src) property to a static import with one of the supported file types: jpg, png, or webp
+- Remove the [`placeholder`](https://nextjs.org/docs/api-reference/next/image#placeholder) property, effectively no blur effect
diff --git a/errors/popstate-state-empty.md b/errors/popstate-state-empty.md
index 433adc2287a5a..ccd98713a557d 100644
--- a/errors/popstate-state-empty.md
+++ b/errors/popstate-state-empty.md
@@ -2,13 +2,13 @@
#### Why This Error Occurred
-When using the browser back button the popstate event is triggered. Next.js sets
-`popstate` event triggered but `event.state` did not have `url` or `as`, causing a route change failure
+When using the browser back button the popstate event is triggered. Next.js sees a
+`popstate` event being triggered but `event.state` did not have `url` or `as`, causing a route change failure.
#### Possible Ways to Fix It
-The only known cause of this issue is manually manipulating `window.history` instead of using `next/router`
+The only known cause of this issue is manually manipulating `window.history` instead of using `next/router`. Starting from version 9.5, Next.js will ignore `popstate` events that contain `event.state` not created by its own router.
### Useful Links
-- [The issue this was reported in: #4994](https://github.com/zeit/next.js/issues/4994)
+- [The issue this was reported in: #4994](https://github.com/vercel/next.js/issues/4994)
diff --git a/errors/postcss-function.md b/errors/postcss-function.md
new file mode 100644
index 0000000000000..83b301eb9d082
--- /dev/null
+++ b/errors/postcss-function.md
@@ -0,0 +1,30 @@
+# PostCSS Configuration Is a Function
+
+#### Why This Error Occurred
+
+The project's custom PostCSS configuration exports a function instead of an object.
+
+#### Possible Ways to Fix It
+
+Adjust the custom PostCSS configuration to not export a function.
+Instead, return a plain object—if you need environment information, read it from `process.env`.
+
+**Before**
+
+```js
+module.exports = ({ env }) => ({
+ plugins: {
+ 'postcss-plugin': env === 'production' ? {} : false,
+ },
+})
+```
+
+**After**
+
+```js
+module.exports = {
+ plugins: {
+ 'postcss-plugin': process.env.NODE_ENV === 'production' ? {} : false,
+ },
+}
+```
diff --git a/errors/postcss-ignored-plugin.md b/errors/postcss-ignored-plugin.md
new file mode 100644
index 0000000000000..e8c73f1c69965
--- /dev/null
+++ b/errors/postcss-ignored-plugin.md
@@ -0,0 +1,20 @@
+# Ignored PostCSS Plugin
+
+#### Why This Error Occurred
+
+The project's custom PostCSS configuration attempts to configure unnecessary plugins:
+
+- postcss-modules-values
+- postcss-modules-scope
+- postcss-modules-extract-imports
+- postcss-modules-local-by-default
+- postcss-modules
+
+#### Possible Ways to Fix It
+
+Remove the plugin specified in the error message from your custom PostCSS configuration.
+
+#### How do I configure CSS Modules?
+
+CSS Modules are supported in [Next.js' built-in CSS support](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
+You can [read more about how to use CSS Modules here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
diff --git a/errors/postcss-shape.md b/errors/postcss-shape.md
new file mode 100644
index 0000000000000..f121c889d04b1
--- /dev/null
+++ b/errors/postcss-shape.md
@@ -0,0 +1,129 @@
+# Invalid PostCSS Configuration
+
+#### Why This Error Occurred
+
+PostCSS configuration was provided in an unsupported shape.
+
+#### Possible Ways to Fix It
+
+PostCSS configuration must be defined in the following shape:
+
+```js
+module.exports = {
+ plugins: [
+ // A plugin that does not require configuration:
+ 'simple-plugin-example',
+
+ // A plugin which needs a configuration object:
+ [
+ 'plugin-with-configuration',
+ {
+ optionA: '...',
+ },
+ ],
+
+ // A plugin that is toggled on or off based on environment:
+ [
+ 'plugin-toggled',
+ process.env.NODE_ENV === 'production'
+ ? {
+ optionA: '...',
+ }
+ : false,
+ ],
+
+ // Boolean expressions are also valid.
+ // `true` enables the plugin, `false` disables the plugin:
+ ['plugin-toggled-2', true /* a === b, etc */],
+ ],
+}
+```
+
+You can [read more about configuring PostCSS in Next.js here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
+
+#### Common Errors
+
+**Before: plugin is require()'d**
+
+```js
+const pluginA = require('postcss-plugin-a')
+module.exports = {
+ plugins: [require('postcss-plugin'), pluginA],
+}
+```
+
+**After**
+
+```js
+module.exports = {
+ plugins: ['postcss-plugin', 'postcss-plugin-a'],
+}
+```
+
+---
+
+**Before: plugin is instantiated with configuration**
+
+```js
+module.exports = {
+ plugins: [
+ require('postcss-plugin')({
+ optionA: '...',
+ }),
+ ],
+}
+```
+
+**After**
+
+```js
+module.exports = {
+ plugins: [
+ // Pay attention to this nested array. The first index is the plugin name,
+ // the second index is the configuration.
+ [
+ 'postcss-plugin',
+ {
+ optionA: '...',
+ },
+ ],
+ ],
+}
+```
+
+---
+
+**Before: plugin is missing configuration**
+
+```js
+module.exports = {
+ plugins: [
+ [
+ 'postcss-plugin-1',
+ {
+ optionA: '...',
+ },
+ ],
+ // This single-entry array is detected as misconfigured because it's
+ // missing the second element. To fix, unwrap the value.
+ ['postcss-plugin-2'],
+ ],
+}
+```
+
+**After**
+
+```js
+module.exports = {
+ plugins: [
+ [
+ 'postcss-plugin-1',
+ {
+ optionA: '...',
+ },
+ ],
+ // Only string:
+ 'postcss-plugin-2',
+ ],
+}
+```
diff --git a/errors/prefetch-true-deprecated.md b/errors/prefetch-true-deprecated.md
new file mode 100644
index 0000000000000..77733fea94726
--- /dev/null
+++ b/errors/prefetch-true-deprecated.md
@@ -0,0 +1,21 @@
+# `prefetch={true}` is deprecated
+
+#### Why This Error Occurred
+
+See https://nextjs.org/blog/next-9#prefetching-in-viewport-links
+
+ will automatically prefetch pages in the background as they appear in the view. If certain pages are rarely visited you can manually set prefetch to false, here's how:
+
+Next.js 9 will automatically prefetch components as they appear in-viewport.
+
+This feature improves the responsiveness of your application by making navigations to new pages quicker.
+
+Next.js uses an Intersection Observer to prefetch the assets necessary in the background.
+
+These requests have low-priority and yield to fetch() or XHR requests. Next.js will avoid automatically prefetching if the user has data-saver enabled.
+
+#### Possible Ways to Fix It
+
+The prefetch attribute is no longer needed, when set to true, example: `prefetch={true}`, remove the property.
+
+Prefetching can be turned off with `prefetch={false}`.
diff --git a/errors/prerender-error.md b/errors/prerender-error.md
new file mode 100644
index 0000000000000..f296fcb20f5fd
--- /dev/null
+++ b/errors/prerender-error.md
@@ -0,0 +1,14 @@
+# Prerender Error
+
+#### Why This Error Occurred
+
+While prerendering a page an error occurred. This can occur for many reasons from adding non-pages e.g. `components` to your `pages` folder or expecting props to be populated which are not.
+
+#### Possible Ways to Fix It
+
+- Make sure to move any non-pages out of the `pages` folder
+- Check for any code that assumes a prop is available, even when it might not be
+- Set default values for all dynamic pages' props (avoid `undefined`, use `null` instead so it can be serialized)
+- Check for any out of date modules that you might be relying on
+- Make sure your component handles `fallback` if it is enabled in `getStaticPaths`. [Fallback docs](https://nextjs.org/docs/api-reference/data-fetching/get-static-paths#fallback-false)
+- Make sure you are not trying to export (`next export`) pages that have server-side rendering enabled [(getServerSideProps)](https://nextjs.org/docs/basic-features/data-fetching/get-server-side-props)
diff --git a/errors/production-start-no-build-id.md b/errors/production-start-no-build-id.md
new file mode 100644
index 0000000000000..c6c9bfdb93f57
--- /dev/null
+++ b/errors/production-start-no-build-id.md
@@ -0,0 +1,10 @@
+# Could not find a production build
+
+#### Why This Error Occurred
+
+When running `next start` or a custom server in production mode a production build is needed.
+
+#### Possible Ways to Fix It
+
+- Run `next build` to create a production build before booting up the production server.
+- If your intention was to run the development server run `next dev` instead.
diff --git a/errors/promise-in-next-config.md b/errors/promise-in-next-config.md
index 781bf04972a87..84ac204fa85c9 100644
--- a/errors/promise-in-next-config.md
+++ b/errors/promise-in-next-config.md
@@ -6,14 +6,16 @@ The webpack function in `next.config.js` returned a promise which is not support
```js
module.exports = {
- webpack: async function(config) {
+ webpack: async function (config) {
return config
- }
+ },
}
```
#### Possible Ways to Fix It
-Check your `next.config.js` for `async` or `return Promise`
+In Next.js versions above `12.0.10`, `module.exports = async () =>` is supported.
+
+For older versions, you can check your `next.config.js` for `async` or `return Promise`.
Potentially a plugin is returning a `Promise` from the webpack function.
diff --git a/errors/public-next-folder-conflict.md b/errors/public-next-folder-conflict.md
new file mode 100644
index 0000000000000..7168b9a1c0cb8
--- /dev/null
+++ b/errors/public-next-folder-conflict.md
@@ -0,0 +1,9 @@
+# Public \_next folder Conflict
+
+#### Why This Error Occurred
+
+In your `./public` folder you added a `_next` folder which conflicts with the internal usage of `_next`. Due to this conflicting this folder name is not allowed inside of your `public` folder.
+
+#### Possible Ways to Fix It
+
+Rename the `_next` folder in your `public` folder to something else or remove it.
diff --git a/errors/react-hydration-error.md b/errors/react-hydration-error.md
new file mode 100644
index 0000000000000..26d65c5516767
--- /dev/null
+++ b/errors/react-hydration-error.md
@@ -0,0 +1,88 @@
+# React Hydration Error
+
+#### Why This Error Occurred
+
+While rendering your application, there was a difference between the React tree that was pre-rendered (SSR/SSG) and the React tree that rendered during the first render in the Browser. The first render is called Hydration which is a [feature of React](https://reactjs.org/docs/react-dom.html#hydrate).
+
+This can cause the React tree to be out of sync with the DOM and result in unexpected content/attributes being present.
+
+#### Possible Ways to Fix It
+
+In general this issue is caused by using a specific library or application code that is relying on something that could differ between pre-rendering and the browser. An example of this is using `window` in a component's rendering.
+
+An example:
+
+```jsx
+function MyComponent() {
+ // This condition depends on `window`. During the first render of the browser the `color` variable will be different
+ const color = typeof window !== 'undefined' ? 'red' : 'blue'
+ // As color is passed as a prop there is a mismatch between what was rendered server-side vs what was rendered in the first render
+ return
Hello World!
+}
+```
+
+How to fix it:
+
+```jsx
+// In order to prevent the first render from being different you can use `useEffect` which is only executed in the browser and is executed during hydration
+import { useEffect, useState } from 'react'
+function MyComponent() {
+ // The default value is 'blue', it will be used during pre-rendering and the first render in the browser (hydration)
+ const [color, setColor] = useState('blue')
+ // During hydration `useEffect` is called. `window` is available in `useEffect`. In this case because we know we're in the browser checking for window is not needed. If you need to read something from window that is fine.
+ // By calling `setColor` in `useEffect` a render is triggered after hydrating, this causes the "browser specific" value to be available. In this case 'red'.
+ useEffect(() => setColor('red'), [])
+ // As color is a state passed as a prop there is no mismatch between what was rendered server-side vs what was rendered in the first render. After useEffect runs the color is set to 'red'
+ return
Hello World!
+}
+```
+
+Another example:
+
+Invalid HTML may cause hydration mismatch such as div inside p.
+
+```jsx
+export const IncorrectComponent = () => {
+ return (
+
+
+ This is not correct and should never be done because the p tag has been
+ abused
+
+ This is correct and should work because a div is really good for this
+ task.
+
+
+
+ )
+}
+```
+
+Common causes with css-in-js libraries:
+
+- When using Styled Components / Emotion
+ - When css-in-js libraries are not set up for pre-rendering (SSR/SSG) it will often lead to a hydration mismatch. In general this means the application has to follow the Next.js example for the library. For example if `pages/_document` is missing and the Babel plugin is not added.
+ - Possible fix for Styled Components:
+ - If you want to leverage Styled Components with SWC in Next.js 12.1+ you need to [add it to your Next.js config under compiler options](https://nextjs.org/docs/advanced-features/compiler#styled-components): https://github.com/vercel/next.js/tree/canary/examples/with-styled-components
+ - If you want to use Styled Components with Babel, you need `pages/_document` and the Babel plugin: https://github.com/vercel/next.js/tree/canary/examples/with-styled-components-babel
+ - Possible fix for Emotion: https://github.com/vercel/next.js/tree/canary/examples/with-emotion
+- When using other css-in-js libraries
+ - Similar to Styled Components / Emotion css-in-js libraries generally need configuration specified in their examples in the [examples directory](https://github.com/vercel/next.js/tree/canary/examples)
+
+### Useful Links
+
+- [React Hydration Documentation](https://reactjs.org/docs/react-dom-client.html#hydrateroot)
+- [Josh Comeau's article on React Hydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/)
diff --git a/errors/react-version.md b/errors/react-version.md
new file mode 100644
index 0000000000000..700b8f17d51f0
--- /dev/null
+++ b/errors/react-version.md
@@ -0,0 +1,51 @@
+# Minimum React Version
+
+#### Why This Error Occurred
+
+Your project is using an old version of `react` or `react-dom` that does not
+meet the suggested minimum version requirement.
+
+Next.js suggests using, at a minimum, `react@18.2.0` and `react-dom@18.2.0`.
+Older versions of `react` and `react-dom` do work with Next.js, however, they do
+not enable all of Next.js' features.
+
+For example, the following features are not enabled with old React versions:
+
+- [Fast Refresh](https://nextjs.org/docs/basic-features/fast-refresh): instantly
+ view edits to your app without losing component state
+- Component stack trace in development: see the component tree that lead up to
+ an error
+- Hydration mismatch warnings: trace down discrepancies in your React tree that
+ cause performance problems
+
+This list is not exhaustive, but illustrative in the value of upgrading React!
+
+#### Possible Ways to Fix It
+
+**Via npm**
+
+```bash
+npm upgrade react@latest react-dom@latest
+```
+
+**Via Yarn**
+
+```bash
+yarn add react@latest react-dom@latest
+```
+
+**Manually** Open your `package.json` and upgrade `react` and `react-dom`:
+
+```json
+{
+ "dependencies": {
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
+ }
+}
+```
+
+### Useful Links
+
+- [Fast Refresh blog post](https://nextjs.org/blog/next-9-4#fast-refresh)
+- [Fast Refresh docs](https://nextjs.org/docs/basic-features/fast-refresh)
diff --git a/errors/render-no-starting-slash.md b/errors/render-no-starting-slash.md
new file mode 100644
index 0000000000000..dc11b24eb9855
--- /dev/null
+++ b/errors/render-no-starting-slash.md
@@ -0,0 +1,9 @@
+# Rendering Without Starting Slash
+
+#### Why This Error Occurred
+
+When calling `app.render(req, res, path)` the `path` did not begin with a slash (`/`). This causes unexpected behavior and should be corrected.
+
+#### Possible Ways to Fix It
+
+Make sure the `path` being passed to `app.render` always starts with a slash (`/`)
diff --git a/errors/reserved-page-prop.md b/errors/reserved-page-prop.md
new file mode 100644
index 0000000000000..ae83aaababfe9
--- /dev/null
+++ b/errors/reserved-page-prop.md
@@ -0,0 +1,9 @@
+# Reserved Page Prop
+
+#### Why This Error Occurred
+
+In a page's `getInitialProps` a reserved prop was returned. Currently the only reserved page prop is `url` for legacy reasons.
+
+#### Possible Ways to Fix It
+
+Change the name of the prop returned from `getInitialProps` to any other name.
diff --git a/errors/returning-response-body-in-middleware.md b/errors/returning-response-body-in-middleware.md
new file mode 100644
index 0000000000000..344ce1b278f95
--- /dev/null
+++ b/errors/returning-response-body-in-middleware.md
@@ -0,0 +1,65 @@
+# Returning response body in Middleware
+
+#### Why This Error Occurred
+
+[Middleware](https://nextjs.org/docs/advanced-features/middleware) can no longer produce a response body as of `v12.2+`.
+
+#### Possible Ways to Fix It
+
+Migrate to using `rewrite`/`redirect` to Pages/API Routes handling a response.
+
+#### Explanation
+
+To respect the differences in client-side and server-side navigation, and to help ensure that developers do not build insecure Middleware, Middleware can no longer produce a response body. This ensures that Middleware is only used to `rewrite`, `redirect`, or modify the incoming request (e.g. [setting cookies](https://nextjs.org/docs/advanced-features/middleware#using-cookies)).
+
+The following patterns will no longer work:
+
+```js
+new Response('a text value')
+new Response(streamOrBuffer)
+new Response(JSON.stringify(obj), { headers: 'application/json' })
+NextResponse.json()
+```
+
+### How to upgrade
+
+For cases where Middleware is used to respond (such as authorization), you should migrate to use `rewrite`/`redirect` to pages that show an authorization error, login forms, or to an API Route.
+
+#### Before
+
+```typescript
+// pages/_middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+import { isAuthValid } from './lib/auth'
+
+export function middleware(request: NextRequest) {
+ // Example function to validate auth
+ if (isAuthValid(request)) {
+ return NextResponse.next()
+ }
+
+ return NextResponse.json({ message: 'Auth required' }, { status: 401 })
+}
+```
+
+#### After
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+import { isAuthValid } from './lib/auth'
+
+export function middleware(request: NextRequest) {
+ // Example function to validate auth
+ if (isAuthValid(request)) {
+ return NextResponse.next()
+ }
+
+ request.nextUrl.searchParams.set('from', request.nextUrl.pathname)
+ request.nextUrl.pathname = '/login'
+
+ return NextResponse.redirect(request.nextUrl)
+}
+```
diff --git a/errors/rewrite-auto-export-fallback.md b/errors/rewrite-auto-export-fallback.md
new file mode 100644
index 0000000000000..af712a447757f
--- /dev/null
+++ b/errors/rewrite-auto-export-fallback.md
@@ -0,0 +1,18 @@
+# Rewriting to Auto Export or Fallback Dynamic Route
+
+#### Why This Error Occurred
+
+One of your rewrites in your `next.config.js` point to a [dynamic route](https://nextjs.org/docs/routing/dynamic-routes) that is automatically statically optimized or is a [fallback SSG page](https://nextjs.org/docs/basic-features/data-fetching#the-fallback-key-required).
+
+Rewriting to these pages are not yet supported since rewrites are not available client-side and the dynamic route params are unable to be parsed. Support for this may be added in a future release.
+
+#### Possible Ways to Fix It
+
+For fallback SSG pages you can add the page to the list of [prerendered paths](https://nextjs.org/docs/basic-features/data-fetching#the-paths-key-required).
+
+For static dynamic routes, you will currently need to either rewrite to non-dynamic route or opt the page out of the static optimization with [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md)
+
+### Useful Links
+
+- [Dynamic Routes Documentation](https://nextjs.org/docs/routing/dynamic-routes)
+- [Fallback Documentation](https://nextjs.org/docs/basic-features/data-fetching#the-fallback-key-required)
diff --git a/errors/routes-must-be-array.md b/errors/routes-must-be-array.md
new file mode 100644
index 0000000000000..59b1875653ec6
--- /dev/null
+++ b/errors/routes-must-be-array.md
@@ -0,0 +1,38 @@
+# Custom Routes must return an array
+
+#### Why This Error Occurred
+
+When defining custom routes an array wasn't returned from either `headers`, `rewrites`, or `redirects`.
+
+#### Possible Ways to Fix It
+
+Make sure to return an array that contains the routes.
+
+**Before**
+
+```js
+// next.config.js
+module.exports = {
+ async rewrites() {
+ return {
+ source: '/feedback',
+ destination: '/feedback/general',
+ }
+ },
+}
+```
+
+**After**
+
+```js
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/feedback',
+ destination: '/feedback/general',
+ },
+ ]
+ },
+}
+```
diff --git a/errors/serverless-publicRuntimeConfig.md b/errors/serverless-publicRuntimeConfig.md
deleted file mode 100644
index e6feecbe19111..0000000000000
--- a/errors/serverless-publicRuntimeConfig.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Using `publicRuntimeConfig` with `target` set to `serverless`
-
-#### Why This Error Occurred
-
-In the `serverless` target environment `next.config.js` is not loaded, so we don't support `publicRuntimeConfig`.
-#### Possible Ways to Fix It
-
-Use config option `env` to set **build time** variables like such:
-
-```js
-// next.config.js
-module.exports = {
- env: {
- special: "value"
- }
-}
-```
-
-```js
-// pages/index.js
-console.log(process.env.special) // value
-```
\ No newline at end of file
diff --git a/errors/sharp-missing-in-production.md b/errors/sharp-missing-in-production.md
new file mode 100644
index 0000000000000..d7c70fde8169a
--- /dev/null
+++ b/errors/sharp-missing-in-production.md
@@ -0,0 +1,41 @@
+# Sharp Missing In Production
+
+#### Why This Error Occurred
+
+The `next/image` component's default loader uses [`squoosh`](https://www.npmjs.com/package/@squoosh/lib) because it is quick to install and suitable for a development environment.
+
+- For a production environment using `next start`, it is strongly recommended you install [`sharp`](https://www.npmjs.com/package/sharp).
+
+You are seeing this error because Image Optimization in production mode (`next start`) was detected.
+
+- For a production environment using `output: "standalone"`, you must install [`sharp`](https://www.npmjs.com/package/sharp).
+
+You are seeing this error because Image Optimization in standalone mode (`output: "standalone"`) was detected.
+
+#### Possible Ways to Fix It
+
+- Install `sharp` by running one of the following commands in your project directory:
+
+```bash
+npm i sharp
+```
+
+```bash
+yarn add sharp
+```
+
+```bash
+pnpm add sharp
+```
+
+Then, build your project with `next build`. Finally, restart the server with either `next start` for production mode or `node server.js` for standalone mode.
+
+- If `sharp` is already installed but can't be resolved, set the `NEXT_SHARP_PATH` environment variable such as `export NEXT_SHARP_PATH=/tmp/node_modules/sharp`. Then, build your project with `next build`. Finally, restart the server with either `next start` for production mode or `node server.js` for standalone mode.
+
+> Note: This is not necessary for Vercel deployments, since `sharp` is installed automatically for you.
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)
+- [Output File Tracing](/docs/advanced-features/output-file-tracing)
diff --git a/errors/sharp-version-avif.md b/errors/sharp-version-avif.md
new file mode 100644
index 0000000000000..dcd90aea36629
--- /dev/null
+++ b/errors/sharp-version-avif.md
@@ -0,0 +1,24 @@
+# Sharp Version Does Not Support AVIF
+
+#### Why This Error Occurred
+
+The `next/image` component's default loader uses [`sharp`](https://www.npmjs.com/package/sharp) if its installed.
+
+You are seeing this error because you have an outdated version of [`sharp`](https://www.npmjs.com/package/sharp) installed that does not support the AVIF image format.
+
+AVIF support was added to [`sharp`](https://www.npmjs.com/package/sharp) in version 0.27.0 (December 2020) so your installed version is likely older.
+
+#### Possible Ways to Fix It
+
+- Install the latest version of `sharp` by running `yarn add sharp@latest` in your project directory
+- If you're using the `NEXT_SHARP_PATH` environment variable, then update the `sharp` install referenced in that path, for example `cd "$NEXT_SHARP_PATH/../" && yarn add sharp@latest`
+- If you cannot upgrade `sharp`, you can instead disable AVIF by configuring [`formats`](https://nextjs.org/docs/api-reference/next/image#image-formats) in your `next.config.js`
+
+After choosing an option above, reboot the server by running either `next dev` or `next start` for development or production respectively.
+
+> Note: This is not necessary for Vercel deployments, since `sharp` is installed automatically for you.
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)
diff --git a/errors/ssg-fallback-true-export.md b/errors/ssg-fallback-true-export.md
new file mode 100644
index 0000000000000..34bd4839526bb
--- /dev/null
+++ b/errors/ssg-fallback-true-export.md
@@ -0,0 +1,14 @@
+# SSG `fallback: true` Export Error
+
+#### Why This Error Occurred
+
+You attempted to export a page with a `fallback: true` return value from `getStaticPaths` which is invalid. `fallback: true` is meant for building pages on-demand after a build has occurred, exporting disables this functionality
+
+#### Possible Ways to Fix It
+
+If you would like the `fallback: true` behavior, `next export` should not be used. Instead follow the [deployment documentation](https://nextjs.org/docs/deployment) to deploy your incrementally generated static site.
+
+### Useful Links
+
+- [deployment documentation](https://nextjs.org/docs/deployment#vercel-recommended)
+- [`fallback: true` documentation](https://nextjs.org/docs/api-reference/data-fetching/get-static-paths#fallback-true)
diff --git a/errors/static-dir-deprecated.md b/errors/static-dir-deprecated.md
new file mode 100644
index 0000000000000..76e13986aed9a
--- /dev/null
+++ b/errors/static-dir-deprecated.md
@@ -0,0 +1,38 @@
+# Static directory is deprecated
+
+#### Why This Error Occurred
+
+In versions prior to 9.0.6 the `static` directory was used to serve static assets in a Next.js application. This has been deprecated in favor of a `public` directory.
+
+The reason we want to support a `public` directory instead is to not require the `/static` prefix for assets anymore and there is no reason to maintain both paths.
+
+#### Possible Ways to Fix It
+
+You can move your `static` directory inside of the `public` directory and all URLs will stay the same as they were before.
+
+**Before**
+
+```
+static/
+ my-image.jpg
+pages/
+ index.js
+components/
+ my-image.js
+```
+
+**After**
+
+```
+public/
+ static/
+ my-image.jpg
+pages/
+ index.js
+components/
+ my-image.js
+```
+
+### Useful Links
+
+- [Static file serving docs](https://nextjs.org/docs/basic-features/static-file-serving)
diff --git a/errors/static-page-generation-timeout.md b/errors/static-page-generation-timeout.md
new file mode 100644
index 0000000000000..c8cc05e24f341
--- /dev/null
+++ b/errors/static-page-generation-timeout.md
@@ -0,0 +1,19 @@
+# Static page generation timed out after multiple attempts
+
+#### Why This Error Occurred
+
+Next.js tries to restart the worker pool of the static page generation when no progress happens for a while, to avoid hanging builds.
+
+When restarted it will retry all uncompleted jobs, but if a job was unsuccessfully attempted multiple times, this will lead to an error.
+
+#### Possible Ways to Fix It
+
+- Make sure that there is no infinite loop during execution.
+- Make sure all Promises in `getStaticPaths`/`getStaticProps` `resolve` or `reject` correctly.
+- Avoid very long timeouts for network requests.
+- Increase the timeout by changing the `staticPageGenerationTimeout` configuration option (default `60` in seconds).
+
+### Useful Links
+
+- [`getStaticPaths`](https://nextjs.org/docs/basic-features/data-fetching/get-static-paths.md)
+- [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching/get-static-props.md)
diff --git a/errors/swc-disabled.md b/errors/swc-disabled.md
new file mode 100644
index 0000000000000..277aaf374d838
--- /dev/null
+++ b/errors/swc-disabled.md
@@ -0,0 +1,28 @@
+# SWC disabled
+
+#### Why This Message Occurred
+
+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](https://nextjs.org/docs/advanced-features/customizing-babel-config). 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.
+
+Many of the integrations with external libraries that currently require custom Babel transformations will be ported to Rust-based SWC transforms in the near future. These include but are not limited to:
+
+- Emotion
+
+In order to prioritize transforms that will help you adopt SWC please provide your `.babelrc` on [the feedback thread](https://github.com/vercel/next.js/discussions/30174).
+
+#### Possible Ways to Fix It
+
+If you want to use SWC despite the presence of a `.babelrc` file you can force it in your `next.config.js` file.
+
+```js
+// next.config.js
+module.exports = {
+ experimental: {
+ forceSwcTransforms: true,
+ },
+}
+```
diff --git a/errors/swc-minify-enabled.md b/errors/swc-minify-enabled.md
new file mode 100644
index 0000000000000..712affcf27a7a
--- /dev/null
+++ b/errors/swc-minify-enabled.md
@@ -0,0 +1,7 @@
+# SWC minify enabled
+
+#### Why This Message Occurred
+
+The application has enabled `swcMinify` in `next.config.js`. By opting in minification will happen using the [SWC](https://swc.rs) minifier instead of Terser. This new minifier is 7x faster than Terser with comparable output. We're actively working on optimizing the output size and minification speed further.
+
+If you have feedback about the minification, please provide it on [the feedback thread](https://github.com/vercel/next.js/discussions/30237).
diff --git a/errors/template.txt b/errors/template.txt
new file mode 100644
index 0000000000000..5905279b86266
--- /dev/null
+++ b/errors/template.txt
@@ -0,0 +1,17 @@
+# {{title}}
+
+#### Why This Error Occurred
+
+
+
+{{why}}
+
+#### Possible Ways to Fix It
+
+
+
+{{fix}}
+
+### Useful Links
+
+
diff --git a/errors/threw-undefined.md b/errors/threw-undefined.md
index 79dd763b2bb8e..4804488cafc49 100644
--- a/errors/threw-undefined.md
+++ b/errors/threw-undefined.md
@@ -1,10 +1,21 @@
-# Threw undefined in render
+# Threw `undefined`/`null`
#### Why This Error Occurred
-Somewhere in your code you `throw` an `undefined` value. Since this isn't a valid error there isn't a stack trace. We show this error instead to let you know what to look for.
+Somewhere in your code you `throw` an `undefined` or `null` value. Since this isn't a valid error there isn't a stack trace. We show this error instead to let you know what to look for.
+```js
+function getData() {
+ let error
+ throw error
+}
+
+function Page() {
+ const error = data?.error || null
+ throw error
+}
+```
#### Possible Ways to Fix It
-Look in your pages and find where an error could be throwing `undefined`
+Look in your pages and find where an error could be throwing `undefined` or `null` values and ensure `new Error()` is used instead.
diff --git a/errors/undefined-webpack-config.md b/errors/undefined-webpack-config.md
new file mode 100644
index 0000000000000..fb15fdb731ba9
--- /dev/null
+++ b/errors/undefined-webpack-config.md
@@ -0,0 +1,28 @@
+# Missing webpack config
+
+#### Why This Error Occurred
+
+The value returned from the custom `webpack` function in your `next.config.js` was undefined. This can occur from the initial config value not being returned.
+
+#### Possible Ways to Fix It
+
+Make sure to return the `webpack` config from your custom `webpack` function in your `next.config.js`
+
+```js
+// next.config.js
+
+module.exports = {
+ webpack: (config, { buildId, dev, isServer, defaultLoaders, webpack }) => {
+ // Note: we provide webpack above so you should not `require` it
+ // Perform customizations to webpack config
+ config.plugins.push(new webpack.IgnorePlugin(/\/__tests__\//))
+
+ // Important: return the modified config
+ return config
+ },
+}
+```
+
+### Useful Links
+
+- [Custom webpack config Documentation](https://nextjs.org/docs/api-reference/next.config.js/custom-webpack-config)
diff --git a/errors/url-deprecated.md b/errors/url-deprecated.md
index 3152f1427773b..df352d8e07068 100644
--- a/errors/url-deprecated.md
+++ b/errors/url-deprecated.md
@@ -10,9 +10,9 @@ The reason this is going away is that we want to make things very predictable an
#### Possible Ways to Fix It
-https://github.com/zeit/next-codemod#url-to-withrouter
+https://nextjs.org/docs/advanced-features/codemods#url-to-withrouter
-Since Next 5 we provide a way to explicitly inject the Next.js router object into pages and all their decending components.
+Since Next 5 we provide a way to explicitly inject the Next.js router object into pages and all their descending components.
The `router` property that is injected will hold the same values as `url`, like `pathname`, `asPath`, and `query`.
Here's an example of using `withRouter`:
@@ -22,7 +22,7 @@ import { withRouter } from 'next/router'
class Page extends React.Component {
render() {
- const {router} = this.props
+ const { router } = this.props
console.log(router)
return
{router.pathname}
}
@@ -33,4 +33,4 @@ export default withRouter(Page)
We provide a codemod (a code to code transformation) to automatically change the `url` property usages to `withRouter`.
-You can find this codemod and instructions on how to run it here: https://github.com/zeit/next-codemod#url-to-withrouter
+You can find this codemod and instructions on how to run it here: https://nextjs.org/docs/advanced-features/codemods#url-to-withrouter
diff --git a/errors/webpack5.md b/errors/webpack5.md
new file mode 100644
index 0000000000000..a7f0d6f72bcde
--- /dev/null
+++ b/errors/webpack5.md
@@ -0,0 +1,46 @@
+# Webpack 5 Adoption
+
+#### Why This Message Occurred
+
+Next.js has adopted webpack 5 as the default for compilation. We've spent a lot of effort into ensuring the transition from webpack 4 to 5 will be as smooth as possible.
+
+Your application currently has webpack 5 disabled using the `webpack5: false` flag which has been removed in Next.js 12:
+
+```js
+module.exports = {
+ // Webpack 5 is enabled by default
+ // You can still use webpack 4 while upgrading to the latest version of Next.js by adding the "webpack5: false" flag
+ webpack5: false,
+}
+```
+
+Using webpack 5 in your application has many benefits, notably:
+
+- Improved Disk Caching: `next build` is significantly faster on subsequent builds
+- Improved Fast Refresh: Fast Refresh work is prioritized
+- Improved Long Term Caching of Assets: Deterministic code output that is less likely to change between builds
+- Improved Tree Shaking
+- Support for assets using `new URL("file.png", import.meta.url)`
+- Support for web workers using `new Worker(new URL("worker.js", import.meta.url))`
+- Support for `exports`/`imports` field in `package.json`
+
+In the past releases we have gradually rolled out webpack 5 to Next.js applications:
+
+- In Next.js 10.2 we automatically opted-in applications without custom webpack configuration in `next.config.js`
+- In Next.js 10.2 we automatically opted-in applications that do not have a `next.config.js`
+- In Next.js 11 webpack 5 was enabled by default for all applications. You could still opt-out and use webpack 4 to help with backwards compatibility using `webpack5: false` in `next.config.js`
+- In Next.js 12 webpack 4 support was removed.
+
+#### Custom webpack configuration
+
+In case you do have custom webpack configuration, either through custom plugins or your own modifications you'll have to take a few steps to ensure your applications works with webpack 5.
+
+- When using `next-transpile-modules` make sure you use the latest version which includes [this patch](https://github.com/martpie/next-transpile-modules/pull/179)
+- When using `@zeit/next-css` / `@zeit/next-sass` make sure you use the [built-in CSS/Sass support](https://nextjs.org/docs/basic-features/built-in-css-support) instead
+- When using `@zeit/next-preact` use [this example](https://github.com/vercel/next.js/tree/canary/examples/using-preact) instead
+- When using `@zeit/next-source-maps` use the [built-in production Source Map support](https://nextjs.org/docs/advanced-features/source-maps)
+- When using webpack plugins make sure they're upgraded to the latest version, in most cases the latest version will include webpack 5 support. In some cases these upgraded webpack plugins will only support webpack 5.
+
+### Useful Links
+
+In case you're running into issues you can connect with the community in [this help discussion](https://github.com/vercel/next.js/discussions/23498).
diff --git a/examples/active-class-name/.gitignore b/examples/active-class-name/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/active-class-name/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/active-class-name/README.md b/examples/active-class-name/README.md
index da1e3c7af9d3f..d418acf07f177 100644
--- a/examples/active-class-name/README.md
+++ b/examples/active-class-name/README.md
@@ -1,44 +1,27 @@
-[](https://deploy.now.sh/?repo=https://github.com/zeit/next.js/tree/master/examples/active-class-name)
-
# activeClassName example
-## How to use
+ReactRouter has a convenience property on the `Link` element to allow an author to set the _active_ className on a link. This example replicates that functionality using Next's own `Link`.
-### Using `create-next-app`
+## Deploy your own
-Execute [`create-next-app`](https://github.com/segmentio/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example:
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/active-class-name)
-```bash
-npx create-next-app --example active-class-name active-class-name-app
-# or
-yarn create next-app --example active-class-name active-class-name-app
-```
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/active-class-name&project-name=active-class-name&repository-name=active-class-name)
-### Download manually
+## How to use
-Download the example:
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/active-class-name
-cd active-class-name
+npx create-next-app --example active-class-name active-class-name-app
```
-Install it and run:
-
```bash
-npm install
-npm run dev
-# or
-yarn
-yarn dev
+yarn create next-app --example active-class-name active-class-name-app
```
-Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit.co/download))
-
```bash
-now
+pnpm create next-app --example active-class-name active-class-name-app
```
-## The idea behind the example
-
-ReactRouter has a convenience property on the `Link` element to allow an author to set the _active_ className on a link. This example replicates that functionality using Next's own `Link`.
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/active-class-name/components/ActiveLink.tsx b/examples/active-class-name/components/ActiveLink.tsx
new file mode 100644
index 0000000000000..c9501b52f951d
--- /dev/null
+++ b/examples/active-class-name/components/ActiveLink.tsx
@@ -0,0 +1,63 @@
+import { useRouter } from 'next/router'
+import Link, { LinkProps } from 'next/link'
+import React, { useState, useEffect, ReactElement, Children } from 'react'
+
+type ActiveLinkProps = LinkProps & {
+ children: ReactElement
+ activeClassName: string
+}
+
+const ActiveLink = ({
+ children,
+ activeClassName,
+ ...props
+}: ActiveLinkProps) => {
+ const { asPath, isReady } = useRouter()
+
+ const child = Children.only(children)
+ const childClassName = child.props.className || ''
+ const [className, setClassName] = useState(childClassName)
+
+ useEffect(() => {
+ // Check if the router fields are updated client-side
+ if (isReady) {
+ // Dynamic route will be matched via props.as
+ // Static route will be matched via props.href
+ const linkPathname = new URL(
+ (props.as || props.href) as string,
+ location.href
+ ).pathname
+
+ // Using URL().pathname to get rid of query and hash
+ const activePathname = new URL(asPath, location.href).pathname
+
+ const newClassName =
+ linkPathname === activePathname
+ ? `${childClassName} ${activeClassName}`.trim()
+ : childClassName
+
+ if (newClassName !== className) {
+ setClassName(newClassName)
+ }
+ }
+ }, [
+ asPath,
+ isReady,
+ props.as,
+ props.href,
+ childClassName,
+ activeClassName,
+ setClassName,
+ className,
+ ])
+
+ return (
+
+ {React.cloneElement(child, {
+ className: className || null,
+ })}
+
+ )
+}
+
+export default ActiveLink
diff --git a/examples/active-class-name/components/Link.js b/examples/active-class-name/components/Link.js
deleted file mode 100644
index fc555524184d5..0000000000000
--- a/examples/active-class-name/components/Link.js
+++ /dev/null
@@ -1,20 +0,0 @@
-import { withRouter } from 'next/router'
-import Link from 'next/link'
-import React, { Children } from 'react'
-
-const ActiveLink = ({ router, children, ...props }) => {
- const child = Children.only(children)
-
- let className = child.props.className || null
- if (router.pathname === props.href && props.activeClassName) {
- className = `${className !== null ? className : ''} ${
- props.activeClassName
- }`.trim()
- }
-
- delete props.activeClassName
-
- return {React.cloneElement(child, { className })}
-}
-
-export default withRouter(ActiveLink)
diff --git a/examples/active-class-name/components/Nav.js b/examples/active-class-name/components/Nav.js
deleted file mode 100644
index 93befbfa05093..0000000000000
--- a/examples/active-class-name/components/Nav.js
+++ /dev/null
@@ -1,30 +0,0 @@
-import Link from './Link'
-
-export default () => (
-
-)
diff --git a/examples/active-class-name/components/Nav.tsx b/examples/active-class-name/components/Nav.tsx
new file mode 100644
index 0000000000000..921cc15120bfd
--- /dev/null
+++ b/examples/active-class-name/components/Nav.tsx
@@ -0,0 +1,39 @@
+import ActiveLink from './ActiveLink'
+
+const Nav = () => (
+
+)
+
+export default Nav
diff --git a/examples/active-class-name/next.config.js b/examples/active-class-name/next.config.js
new file mode 100644
index 0000000000000..31164407943d1
--- /dev/null
+++ b/examples/active-class-name/next.config.js
@@ -0,0 +1,11 @@
+/** @type {import('next').NextConfig} */
+module.exports = {
+ async rewrites() {
+ return [
+ {
+ source: '/blog',
+ destination: '/news',
+ },
+ ]
+ },
+}
diff --git a/examples/active-class-name/package.json b/examples/active-class-name/package.json
index feb47ede884f6..6bd281538c2a0 100644
--- a/examples/active-class-name/package.json
+++ b/examples/active-class-name/package.json
@@ -1,16 +1,18 @@
{
- "name": "active-class-name",
- "version": "1.0.0",
+ "private": true,
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
},
- "author": "Remy Sharp ",
"dependencies": {
"next": "latest",
- "react": "^16.7.0",
- "react-dom": "^16.7.0"
+ "react": "18.2.0",
+ "react-dom": "18.2.0"
},
- "license": "ISC"
+ "devDependencies": {
+ "@types/node": "^18.0.0",
+ "@types/react": "^18.0.14",
+ "typescript": "^4.7.4"
+ }
}
diff --git a/examples/active-class-name/pages/[slug].tsx b/examples/active-class-name/pages/[slug].tsx
new file mode 100644
index 0000000000000..0f8f73e5888d0
--- /dev/null
+++ b/examples/active-class-name/pages/[slug].tsx
@@ -0,0 +1,14 @@
+import { useRouter } from 'next/router'
+import Nav from '../components/Nav'
+
+const SlugPage = () => {
+ const { asPath } = useRouter()
+ return (
+ <>
+
+
+ You can import AMP components using next/head. Checkout{' '}
+ components/amp/AmpCustomElement for a simple way to
+ import AMP components. Once the component is imported, you can use
+ it like any other HTML element.
+
+
+
+
+
+
+
+
+
+
+
amp-bind & amp-state
+
+ It's no problem to use amp-bind and{' '}
+ amp-state with Next.js. There are two things to be
+ aware of:
+
+
+ The [...] binding syntax{' '}
+ [text]="myStateVariable"is not supported in JSX.
+ Use data-amp-bind-text="myStateVariable" instead.
+
+
+ Initializing amp-state via JSON string is not
+ supported in JSX:
+
{`
+
+`}
+ Instead you need to use dangerouslySetInnerHTML to
+ initialize the string. can use the{' '}
+ /components/amp/AmpState.js component to see how it
+ works. The same approach works for amp-access and{' '}
+ amp-consent as well
+
+ Mustache templates conflict with JSX and it's template literals need
+ to be escaped. A simple approach is to escape them via back ticks:{' '}
+ src={`{{imageUrl}}`}.
+
+
+
+
+ {/* */}
+
+
+
+
+
+
+
+
+ {/* */}
+
+
+
+ )
+}
+
+export default Home
diff --git a/examples/amp-story/tsconfig.json b/examples/amp-story/tsconfig.json
new file mode 100644
index 0000000000000..114d0ab4942b1
--- /dev/null
+++ b/examples/amp-story/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true
+ },
+ "include": ["next-env.d.ts", "amp.d.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/amp/.gitignore b/examples/amp/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/amp/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/amp/README.md b/examples/amp/README.md
index 9fbdc15d0f77a..8c637dfa89fbb 100644
--- a/examples/amp/README.md
+++ b/examples/amp/README.md
@@ -1,44 +1,27 @@
-[](https://deploy.now.sh/?repo=https://github.com/zeit/next.js/tree/master/examples/amp)
-
# Google AMP
-## How to use
+This example shows how to create AMP pages using Next.js and the AMP feature. It shows a normal page (non-AMP), an AMP only page, and a hybrid AMP page.
-### Using `create-next-app`
+## Deploy your own
-Execute [`create-next-app`](https://github.com/segmentio/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example:
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
-```bash
-npx create-next-app --example amp amp-app
-# or
-yarn create next-app --example amp amp-app
-```
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/amp&project-name=amp&repository-name=amp)
-### Download manually
+## How to use
-Download the example:
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
```bash
-curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/amp
-cd amp
+npx create-next-app --example amp amp-app
```
-Install it and run:
-
```bash
-npm install
-npm run dev
-# or
-yarn
-yarn dev
+yarn create next-app --example amp amp-app
```
-Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit.co/download))
-
```bash
-now
+pnpm create next-app --example amp amp-app
```
-## The idea behind the example
-
-This example shows how to create AMP pages using Next.js and the experimental AMP feature. It shows a normal page (non-AMP), an AMP only page, and a hybrid AMP page.
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/amp/additional.d.ts b/examples/amp/additional.d.ts
new file mode 100644
index 0000000000000..8cb81833b62f8
--- /dev/null
+++ b/examples/amp/additional.d.ts
@@ -0,0 +1,31 @@
+// Allow AMP elements to be a property on JSX.IntrinsicElements
+
+// Only the intrinsic elements defined here will be accepted, and only with the attributes defined here
+declare namespace JSX {
+ interface AmpImg {
+ alt?: string
+ src?: string
+ width?: string | number
+ height?: string | number
+ layout?: string
+ fallback?: string
+ children?: React.ReactNode
+ }
+ interface IntrinsicElements {
+ 'amp-img': AmpImg
+ }
+}
+
+// Only the intrinsic elements defined here will be accepted, attributes don't matter
+// declare namespace JSX {
+// interface IntrinsicElements {
+// 'amp-img': any;
+// }
+// }
+
+// All intrinsic elements will be accepted
+// declare namespace JSX {
+// interface IntrinsicElements {
+// [elemName: string]: any;
+// }
+// }
diff --git a/examples/amp/components/Byline.js b/examples/amp/components/Byline.js
deleted file mode 100644
index 51c000653e7d0..0000000000000
--- a/examples/amp/components/Byline.js
+++ /dev/null
@@ -1,11 +0,0 @@
-export default ({ author }) => (
- <>
-
- Cat ipsum dolor sit amet,
- eat grass, throw it back up but refuse to leave cardboard box or groom
- yourself 4 hours - checked, have your beauty sleep 18 hours - checked,
- be fabulous for the rest of the day - checked!. Hide from vacuum
- cleaner. Chirp at birds chew foot chase the pig around the house and
- meoooow!. Chase ball of string climb a tree, wait for a fireman jump to
- fireman then scratch his face claw drapes, for meow to be let in yet
- attack dog, run away and pretend to be victim meow loudly just to annoy
- owners. Touch water with paw then recoil in horror hide when guests come
- over, and tuxedo cats always looking dapper so has closed eyes but still
- sees you or a nice warm laptop for me to sit on pee in human's bed until
- he cleans the litter box. Steal the warm chair right after you get up
- cat not kitten around yet claws in your leg eat all the power cords.
- Lick sellotape curl into a furry donut immediately regret falling into
- bathtub or you call this cat food? and fall asleep on the washing
- machine. Purr for no reason hack up furballs and pelt around the house
- and up and down stairs chasing phantoms. If it smells like fish eat as
- much as you wish. Unwrap toilet paper chew iPad power cord white cat
- sleeps on a black shirt lick the other cats. Lounge in doorway mew. Has
- closed eyes but still sees you sleep on keyboard, so hunt anything that
- moves lick sellotape but slap owner's face at 5am until human fills food
- dish if it smells like fish eat as much as you wish. Meow to be let in
- find empty spot in cupboard and sleep all day and thug cat sit by the
- fire burrow under covers always hungry. Swat at dog hide when guests
- come over purrrrrr chew on cable so mark territory, yet howl on top of
- tall thing or find something else more interesting. Chase mice kitten is
- playing with dead mouse. Sit and stare if it fits, i sits. Mark
- territory damn that dog , but step on your keyboard while you're gaming
- and then turn in a circle put butt in owner's face human give me
- attention meow or eat and than sleep on your face. Friends are not food
- jump around on couch, meow constantly until given food, or walk on car
- leaving trail of paw prints on hood and windshield, and spread kitty
- litter all over house, going to catch the red dot today going to catch
- the red dot today. Jump off balcony, onto stranger's head.
-
-
- Meow to be let out damn that dog howl uncontrollably for no reason
- caticus cuteicus for play riveting piece on synthesizer keyboard. Meow
- loudly just to annoy owners the dog smells bad for eat the fat cats
- food, yet ignore the squirrels, you'll never catch them anyway cat
- snacks spread kitty litter all over house or hopped up on catnip. Spit
- up on light gray carpet instead of adjacent linoleum throwup on your
- pillow, so cat is love, cat is life yet human is washing you why halp oh
- the horror flee scratch hiss bite. Chase mice. Swat turds around the
- house hide at bottom of staircase to trip human. Meowing non stop for
- food howl on top of tall thing. Shake treat bag pee in human's bed until
- he cleans the litter box missing until dinner time. Have secret plans
- climb a tree, wait for a fireman jump to fireman then scratch his face
- bleghbleghvomit my furball really tie the room together. Chase dog then
- run away purr shake treat bag spit up on light gray carpet instead of
- adjacent linoleum but dream about hunting birds. Hiss at vacuum cleaner
- milk the cow lay on arms while you're using the keyboard sleep in the
- bathroom sink. Stare at ceiling touch water with paw then recoil in
- horror or refuse to leave cardboard box. Paw at your fat belly plan
- steps for world domination for going to catch the red dot today going to
- catch the red dot today slap owner's face at 5am until human fills food
- dish scratch at the door then walk away for intrigued by the shower, but
- steal the warm chair right after you get up. Fall asleep on the washing
- machine destroy couch as revenge scream at teh bath so love to play with
- owner's hair tie. Howl uncontrollably for no reason rub whiskers on bare
- skin act innocent. Cats making all the muffins lick butt and make a
- weird face meow all night having their mate disturbing sleeping humans
- human give me attention meow intently stare at the same spot. Sleep on
- dog bed, force dog to sleep on floor spot something, big eyes, big eyes,
- crouch, shake butt, prepare to pounce for wake up human for food at 4am
- or pooping rainbow while flying in a toasted bread costume in space
- sleep on keyboard put toy mouse in food bowl run out of litter box at
- full speed . Jump off balcony, onto stranger's head lick butt and make a
- weird face but go into a room to decide you didn't want to be in there
- anyway so then cats take over the world, pee in human's bed until he
- cleans the litter box and if it fits, i sits caticus cuteicus. Eats
- owners hair then claws head lounge in doorway, and hide when guests come
- over chase ball of string eat owner's food play riveting piece on
- synthesizer keyboard. Purrr purr littel cat, little cat purr purr spit
- up on light gray carpet instead of adjacent linoleum kitty loves pigs
- yet damn that dog meow or walk on car leaving trail of paw prints on
- hood and windshield. Roll on the floor purring your whiskers off meow
- all night having their mate disturbing sleeping humans need to chase
- tail meow hide when guests come over. Soft kitty warm kitty little ball
- of furr destroy the blinds meow leave hair everywhere attack dog, run
- away and pretend to be victim. Going to catch the red dot today going to
- catch the red dot today instantly break out into full speed gallop
- across the house for no reason meow so hide when guests come over, yet
- hide at bottom of staircase to trip human toy mouse squeak roll over
- claws in your leg. Cat slap dog in face lick plastic bags why must they
- do that.
-
-
- Jump launch to pounce upon little yarn mouse, bare fangs at toy run hide
- in litter box until treats are fed touch water with paw then recoil in
- horror then cats take over the world i could pee on this if i had the
- energy. Lie on your belly and purr when you are asleep toy mouse squeak
- roll over so stick butt in face you call this cat food? and behind the
- couch curl up and sleep on the freshly laundered towels yet love to play
- with owner's hair tie. Knock dish off table head butt cant eat out of my
- own dish walk on car leaving trail of paw prints on hood and windshield
- find something else more interesting cats go for world domination, spit
- up on light gray carpet instead of adjacent linoleum sit in box. Missing
- until dinner time put toy mouse in food bowl run out of litter box at
- full speed but poop in the plant pot and nap all day caticus cuteicus.
- Leave hair everywhere attack feet mrow bleghbleghvomit my furball really
- tie the room together meowwww eat grass, throw it back up. Hate dog
- meowzer! find something else more interesting, yet cat snacks, so
- scratch at the door then walk away chase mice. Chase laser scratch the
- box plan steps for world domination massacre a bird in the living room
- and then look like the cutest and most innocent animal on the planet for
- stare at ceiling light and who's the baby. Stare at ceiling Gate keepers
- of hell, for licks paws intently sniff hand. Pooping rainbow while
- flying in a toasted bread costume in space. Gnaw the corn cob. Lick yarn
- hanging out of own butt stare at ceiling lick butt and make a weird face
- eat and than sleep on your face. Meow all night having their mate
- disturbing sleeping humans attack feet, so poop on grasses stare at wall
- turn and meow stare at wall some more meow again continue staring yet
- purr. Have my breakfast spaghetti yarn. Cats secretly make all the
- worlds muffins throwup on your pillow plays league of legends. Lick the
- plastic bag scratch at the door then walk away. Unwrap toilet paper meow
- to be let in walk on car leaving trail of paw prints on hood and
- windshield yet hide from vacuum cleaner or massacre a bird in the living
- room and then look like the cutest and most innocent animal on the
- planet. Purr lick the curtain just to be annoying go into a room to
- decide you didn't want to be in there anyway attack feet, and spit up on
- light gray carpet instead of adjacent linoleum yet lick plastic bags.
- Spit up on light gray carpet instead of adjacent linoleum touch water
- with paw then recoil in horror so cat snacks. Purr. Lick sellotape
- please stop looking at your phone and pet me yet stick butt in face
- meow. Groom yourself 4 hours - checked, have your beauty sleep 18 hours
- - checked, be fabulous for the rest of the day - checked! tuxedo cats
- always looking dapper but purrrrrr. Claws in your leg i could pee on
- this if i had the energy. Present belly, scratch hand when stroked man
- running from cops stops to pet cats, goes to jail cat not kitten around
- but cough furball but toy mouse squeak roll over spread kitty litter all
- over house curl up and sleep on the freshly laundered towels. Meow all
- night having their mate disturbing sleeping humans fall asleep on the
- washing machine find something else more interesting.
-
-
- Ignore the squirrels, you'll never catch them anyway missing until
- dinner time, for intrigued by the shower, so i could pee on this if i
- had the energy for purrrrrr for vommit food and eat it again lick butt
- and make a weird face. Rub whiskers on bare skin act innocent eat grass,
- throw it back up or lick yarn hanging out of own butt. I am the best cat
- is love, cat is life, or sleep nap, mew but meoooow!. Meowzer!. Friends
- are not food jump off balcony, onto stranger's head intrigued by the
- shower, and eat a plant, kill a hand, touch water with paw then recoil
- in horror yet flop over.
-
-
- Step on your keyboard while you're gaming and then turn in a circle wake
- up human for food at 4am so shove bum in owner's face like camera lens
- for see owner, run in terror run outside as soon as door open. Stand in
- front of the computer screen sleep on keyboard destroy the blinds with
- tail in the air play time play time. Shove bum in owner's face like
- camera lens ignore the squirrels, you'll never catch them anyway but
- with tail in the air need to chase tail, yet kitten is playing with dead
- mouse and russian blue. Hopped up on catnip refuse to leave cardboard
- box you call this cat food? walk on car leaving trail of paw prints on
- hood and windshield. Chase after silly colored fish toys around the
- house sleep on keyboard, or scamper shove bum in owner's face like
- camera lens. Groom yourself 4 hours - checked, have your beauty sleep 18
- hours - checked, be fabulous for the rest of the day - checked! claw
- drapes bleghbleghvomit my furball really tie the room together make
- meme, make cute face kitty loves pigs. Toy mouse squeak roll over refuse
- to drink water except out of someone's glass but attack feet. Sleep on
- keyboard. Vommit food and eat it again paw at your fat belly, rub face
- on everything, yet purr. Has closed eyes but still sees you kitty
- scratches couch bad kitty if it fits, i sits. Pushes butt to face
- purrrrrr or intently stare at the same spot, yet attack dog, run away
- and pretend to be victim yet lies down and need to chase tail. Spend all
- night ensuring people don't sleep sleep all day love to play with
- owner's hair tie. I could pee on this if i had the energy lick butt
- stare out the window. Make meme, make cute face. Chase after silly
- colored fish toys around the house. Leave fur on owners clothes poop in
- the plant pot. Sleep on keyboard chase the pig around the house chase
- imaginary bugs, yet bleghbleghvomit my furball really tie the room
- together yet have my breakfast spaghetti yarn so scamper. Need to chase
- tail meow for food, then when human fills food dish, take a few bites of
- food and continue meowing for pee in the shoe thinking longingly about
- tuna brine yet purrr purr littel cat, little cat purr purr lie on your
- belly and purr when you are asleep. Lounge in doorway poop on grasses
- for lounge in doorway for chew iPad power cord.
-
-
-
- )
-})
diff --git a/examples/amp/pages/index.tsx b/examples/amp/pages/index.tsx
new file mode 100644
index 0000000000000..5395cb8f9ee6b
--- /dev/null
+++ b/examples/amp/pages/index.tsx
@@ -0,0 +1,237 @@
+import Head from 'next/head'
+import { useAmp } from 'next/amp'
+import Layout from '../components/Layout'
+import Byline from '../components/Byline'
+
+export const config = {
+ amp: true,
+}
+
+export default function IndexPage() {
+ const isAmp = useAmp()
+
+ return (
+
+
+ The Cat
+
+
The Cat (AMP-first Page)
+
+
Meowwwwwwww
+
+
+
+
+ Cat ipsum dolor sit amet,
+ eat grass, throw it back up but refuse to leave cardboard box or groom
+ yourself 4 hours - checked, have your beauty sleep 18 hours - checked,
+ be fabulous for the rest of the day - checked!. Hide from vacuum
+ cleaner. Chirp at birds chew foot chase the pig around the house and
+ meoooow!. Chase ball of string climb a tree, wait for a fireman jump to
+ fireman then scratch his face claw drapes, for meow to be let in yet
+ attack dog, run away and pretend to be victim meow loudly just to annoy
+ owners. Touch water with paw then recoil in horror hide when guests come
+ over, and tuxedo cats always looking dapper so has closed eyes but still
+ sees you or a nice warm laptop for me to sit on pee in human's bed until
+ he cleans the litter box. Steal the warm chair right after you get up
+ cat not kitten around yet claws in your leg eat all the power cords.
+ Lick sellotape curl into a furry donut immediately regret falling into
+ bathtub or you call this cat food? and fall asleep on the washing
+ machine. Purr for no reason hack up furballs and pelt around the house
+ and up and down stairs chasing phantoms. If it smells like fish eat as
+ much as you wish. Unwrap toilet paper chew iPad power cord white cat
+ sleeps on a black shirt lick the other cats. Lounge in doorway mew. Has
+ closed eyes but still sees you sleep on keyboard, so hunt anything that
+ moves lick sellotape but slap owner's face at 5am until human fills food
+ dish if it smells like fish eat as much as you wish. Meow to be let in
+ find empty spot in cupboard and sleep all day and thug cat sit by the
+ fire burrow under covers always hungry. Swat at dog hide when guests
+ come over purrrrrr chew on cable so mark territory, yet howl on top of
+ tall thing or find something else more interesting. Chase mice kitten is
+ playing with dead mouse. Sit and stare if it fits, i sits. Mark
+ territory damn that dog , but step on your keyboard while you're gaming
+ and then turn in a circle put butt in owner's face human give me
+ attention meow or eat and than sleep on your face. Friends are not food
+ jump around on couch, meow constantly until given food, or walk on car
+ leaving trail of paw prints on hood and windshield, and spread kitty
+ litter all over house, going to catch the red dot today going to catch
+ the red dot today. Jump off balcony, onto stranger's head.
+
+
+ Meow to be let out damn that dog howl uncontrollably for no reason
+ caticus cuteicus for play riveting piece on synthesizer keyboard. Meow
+ loudly just to annoy owners the dog smells bad for eat the fat cats
+ food, yet ignore the squirrels, you'll never catch them anyway cat
+ snacks spread kitty litter all over house or hopped up on catnip. Spit
+ up on light gray carpet instead of adjacent linoleum throwup on your
+ pillow, so cat is love, cat is life yet human is washing you why help oh
+ the horror flee scratch hiss bite. Chase mice. Swat turds around the
+ house hide at bottom of staircase to trip human. Meowing non stop for
+ food howl on top of tall thing. Shake treat bag pee in human's bed until
+ he cleans the litter box missing until dinner time. Have secret plans
+ climb a tree, wait for a fireman jump to fireman then scratch his face
+ bleghbleghvomit my furball really tie the room together. Chase dog then
+ run away purr shake treat bag spit up on light gray carpet instead of
+ adjacent linoleum but dream about hunting birds. Hiss at vacuum cleaner
+ milk the cow lay on arms while you're using the keyboard sleep in the
+ bathroom sink. Stare at ceiling touch water with paw then recoil in
+ horror or refuse to leave cardboard box. Paw at your fat belly plan
+ steps for world domination for going to catch the red dot today going to
+ catch the red dot today slap owner's face at 5am until human fills food
+ dish scratch at the door then walk away for intrigued by the shower, but
+ steal the warm chair right after you get up. Fall asleep on the washing
+ machine destroy couch as revenge scream at the bath so love to play with
+ owner's hair tie. Howl uncontrollably for no reason rub whiskers on bare
+ skin act innocent. Cats making all the muffins lick butt and make a
+ weird face meow all night having their mate disturbing sleeping humans
+ human give me attention meow intently stare at the same spot. Sleep on
+ dog bed, force dog to sleep on floor spot something, big eyes, big eyes,
+ crouch, shake butt, prepare to pounce for wake up human for food at 4am
+ or pooping rainbow while flying in a toasted bread costume in space
+ sleep on keyboard put toy mouse in food bowl run out of litter box at
+ full speed . Jump off balcony, onto stranger's head lick butt and make a
+ weird face but go into a room to decide you didn't want to be in there
+ anyway so then cats take over the world, pee in human's bed until he
+ cleans the litter box and if it fits, i sits caticus cuteicus. Eats
+ owners hair then claws head lounge in doorway, and hide when guests come
+ over chase ball of string eat owner's food play riveting piece on
+ synthesizer keyboard. Purrr purr little cat, little cat purr purr spit
+ up on light gray carpet instead of adjacent linoleum kitty loves pigs
+ yet damn that dog meow or walk on car leaving trail of paw prints on
+ hood and windshield. Roll on the floor purring your whiskers off meow
+ all night having their mate disturbing sleeping humans need to chase
+ tail meow hide when guests come over. Soft kitty warm kitty little ball
+ of furr destroy the blinds meow leave hair everywhere attack dog, run
+ away and pretend to be victim. Going to catch the red dot today going to
+ catch the red dot today instantly break out into full speed gallop
+ across the house for no reason meow so hide when guests come over, yet
+ hide at bottom of staircase to trip human toy mouse squeak roll over
+ claws in your leg. Cat slap dog in face lick plastic bags why must they
+ do that.
+
+
+ Jump launch to pounce upon little yarn mouse, bare fangs at toy run hide
+ in litter box until treats are fed touch water with paw then recoil in
+ horror then cats take over the world i could pee on this if i had the
+ energy. Lie on your belly and purr when you are asleep toy mouse squeak
+ roll over so stick butt in face you call this cat food? and behind the
+ couch curl up and sleep on the freshly laundered towels yet love to play
+ with owner's hair tie. Knock dish off table head butt cant eat out of my
+ own dish walk on car leaving trail of paw prints on hood and windshield
+ find something else more interesting cats go for world domination, spit
+ up on light gray carpet instead of adjacent linoleum sit in box. Missing
+ until dinner time put toy mouse in food bowl run out of litter box at
+ full speed but poop in the plant pot and nap all day caticus cuteicus.
+ Leave hair everywhere attack feet mrow bleghbleghvomit my furball really
+ tie the room together meowwww eat grass, throw it back up. Hate dog
+ meowzer! find something else more interesting, yet cat snacks, so
+ scratch at the door then walk away chase mice. Chase laser scratch the
+ box plan steps for world domination massacre a bird in the living room
+ and then look like the cutest and most innocent animal on the planet for
+ stare at ceiling light and who's the baby. Stare at ceiling Gate keepers
+ of hell, for licks paws intently sniff hand. Pooping rainbow while
+ flying in a toasted bread costume in space. Gnaw the corn cob. Lick yarn
+ hanging out of own butt stare at ceiling lick butt and make a weird face
+ eat and than sleep on your face. Meow all night having their mate
+ disturbing sleeping humans attack feet, so poop on grasses stare at wall
+ turn and meow stare at wall some more meow again continue staring yet
+ purr. Have my breakfast spaghetti yarn. Cats secretly make all the
+ worlds muffins throwup on your pillow plays league of legends. Lick the
+ plastic bag scratch at the door then walk away. Unwrap toilet paper meow
+ to be let in walk on car leaving trail of paw prints on hood and
+ windshield yet hide from vacuum cleaner or massacre a bird in the living
+ room and then look like the cutest and most innocent animal on the
+ planet. Purr lick the curtain just to be annoying go into a room to
+ decide you didn't want to be in there anyway attack feet, and spit up on
+ light gray carpet instead of adjacent linoleum yet lick plastic bags.
+ Spit up on light gray carpet instead of adjacent linoleum touch water
+ with paw then recoil in horror so cat snacks. Purr. Lick sellotape
+ please stop looking at your phone and pet me yet stick butt in face
+ meow. Groom yourself 4 hours - checked, have your beauty sleep 18 hours
+ - checked, be fabulous for the rest of the day - checked! tuxedo cats
+ always looking dapper but purrrrrr. Claws in your leg i could pee on
+ this if i had the energy. Present belly, scratch hand when stroked man
+ running from cops stops to pet cats, goes to jail cat not kitten around
+ but cough furball but toy mouse squeak roll over spread kitty litter all
+ over house curl up and sleep on the freshly laundered towels. Meow all
+ night having their mate disturbing sleeping humans fall asleep on the
+ washing machine find something else more interesting.
+
+
+ Ignore the squirrels, you'll never catch them anyway missing until
+ dinner time, for intrigued by the shower, so i could pee on this if i
+ had the energy for purrrrrr for vommit food and eat it again lick butt
+ and make a weird face. Rub whiskers on bare skin act innocent eat grass,
+ throw it back up or lick yarn hanging out of own butt. I am the best cat
+ is love, cat is life, or sleep nap, mew but meoooow!. Meowzer!. Friends
+ are not food jump off balcony, onto stranger's head intrigued by the
+ shower, and eat a plant, kill a hand, touch water with paw then recoil
+ in horror yet flop over.
+
+
+ Step on your keyboard while you're gaming and then turn in a circle wake
+ up human for food at 4am so shove bum in owner's face like camera lens
+ for see owner, run in terror run outside as soon as door open. Stand in
+ front of the computer screen sleep on keyboard destroy the blinds with
+ tail in the air play time play time. Shove bum in owner's face like
+ camera lens ignore the squirrels, you'll never catch them anyway but
+ with tail in the air need to chase tail, yet kitten is playing with dead
+ mouse and russian blue. Hopped up on catnip refuse to leave cardboard
+ box you call this cat food? walk on car leaving trail of paw prints on
+ hood and windshield. Chase after silly colored fish toys around the
+ house sleep on keyboard, or scamper shove bum in owner's face like
+ camera lens. Groom yourself 4 hours - checked, have your beauty sleep 18
+ hours - checked, be fabulous for the rest of the day - checked! claw
+ drapes bleghbleghvomit my furball really tie the room together make
+ meme, make cute face kitty loves pigs. Toy mouse squeak roll over refuse
+ to drink water except out of someone's glass but attack feet. Sleep on
+ keyboard. Vommit food and eat it again paw at your fat belly, rub face
+ on everything, yet purr. Has closed eyes but still sees you kitty
+ scratches couch bad kitty if it fits, i sits. Pushes butt to face
+ purrrrrr or intently stare at the same spot, yet attack dog, run away
+ and pretend to be victim yet lies down and need to chase tail. Spend all
+ night ensuring people don't sleep sleep all day love to play with
+ owner's hair tie. I could pee on this if i had the energy lick butt
+ stare out the window. Make meme, make cute face. Chase after silly
+ colored fish toys around the house. Leave fur on owners clothes poop in
+ the plant pot. Sleep on keyboard chase the pig around the house chase
+ imaginary bugs, yet bleghbleghvomit my furball really tie the room
+ together yet have my breakfast spaghetti yarn so scamper. Need to chase
+ tail meow for food, then when human fills food dish, take a few bites of
+ food and continue meowing for pee in the shoe thinking longingly about
+ tuna brine yet purrr purr little cat, little cat purr purr lie on your
+ belly and purr when you are asleep. Lounge in doorway poop on grasses
+ for lounge in doorway for chew iPad power cord.
+
+
+
+ )
+}
+
+export default SignUp
diff --git a/examples/api-routes-apollo-server-and-client/.gitignore b/examples/api-routes-apollo-server-and-client/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/api-routes-apollo-server-and-client/README.md b/examples/api-routes-apollo-server-and-client/README.md
new file mode 100644
index 0000000000000..446d8f52a9cdf
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/README.md
@@ -0,0 +1,29 @@
+# Apollo Server and Client Example
+
+[Apollo](https://www.apollographql.com/client/) is a GraphQL client that allows you to easily query the exact data you need from a GraphQL server. In addition to fetching and mutating data, Apollo analyzes your queries and their results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run.
+
+In this simple example, we integrate Apollo seamlessly with [Next.js data fetching methods](https://nextjs.org/docs/basic-features/data-fetching) to fetch queries in the server and hydrate them in the browser.
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-apollo-server-and-client)
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-apollo-server-and-client&project-name=api-routes-apollo-server-and-client&repository-name=api-routes-apollo-server-and-client)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-app
+```
+
+```bash
+yarn create next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-app
+```
+
+```bash
+pnpm create next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/api-routes-apollo-server-and-client/apollo/client.js b/examples/api-routes-apollo-server-and-client/apollo/client.js
new file mode 100644
index 0000000000000..de4dc3b2d110b
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/apollo/client.js
@@ -0,0 +1,55 @@
+import { useMemo } from 'react'
+import { ApolloClient, InMemoryCache } from '@apollo/client'
+import merge from 'deepmerge'
+
+let apolloClient
+
+function createIsomorphLink() {
+ if (typeof window === 'undefined') {
+ const { SchemaLink } = require('@apollo/client/link/schema')
+ const { schema } = require('./schema')
+ return new SchemaLink({ schema })
+ } else {
+ const { HttpLink } = require('@apollo/client/link/http')
+ return new HttpLink({
+ uri: '/api/graphql',
+ credentials: 'same-origin',
+ })
+ }
+}
+
+function createApolloClient() {
+ return new ApolloClient({
+ ssrMode: typeof window === 'undefined',
+ link: createIsomorphLink(),
+ cache: new InMemoryCache(),
+ })
+}
+
+export function initializeApollo(initialState = null) {
+ const _apolloClient = apolloClient ?? createApolloClient()
+
+ // If your page has Next.js data fetching methods that use Apollo Client, the initial state
+ // gets hydrated here
+ if (initialState) {
+ // Get existing cache, loaded during client side data fetching
+ const existingCache = _apolloClient.extract()
+
+ // Merge the existing cache into data passed from getStaticProps/getServerSideProps
+ const data = merge(initialState, existingCache)
+
+ // Restore the cache with the merged data
+ _apolloClient.cache.restore(data)
+ }
+ // For SSG and SSR always create a new Apollo Client
+ if (typeof window === 'undefined') return _apolloClient
+ // Create the Apollo Client once in the client
+ if (!apolloClient) apolloClient = _apolloClient
+
+ return _apolloClient
+}
+
+export function useApollo(initialState) {
+ const store = useMemo(() => initializeApollo(initialState), [initialState])
+ return store
+}
diff --git a/examples/api-routes-apollo-server-and-client/apollo/resolvers.js b/examples/api-routes-apollo-server-and-client/apollo/resolvers.js
new file mode 100644
index 0000000000000..94a103eda6606
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/apollo/resolvers.js
@@ -0,0 +1,7 @@
+export const resolvers = {
+ Query: {
+ viewer(_parent, _args, _context, _info) {
+ return { id: 1, name: 'John Smith', status: 'cached' }
+ },
+ },
+}
diff --git a/examples/api-routes-apollo-server-and-client/apollo/schema.js b/examples/api-routes-apollo-server-and-client/apollo/schema.js
new file mode 100644
index 0000000000000..f6d70b7e86243
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/apollo/schema.js
@@ -0,0 +1,8 @@
+import { makeExecutableSchema } from 'graphql-tools'
+import { typeDefs } from './type-defs'
+import { resolvers } from './resolvers'
+
+export const schema = makeExecutableSchema({
+ typeDefs,
+ resolvers,
+})
diff --git a/examples/api-routes-apollo-server-and-client/apollo/type-defs.js b/examples/api-routes-apollo-server-and-client/apollo/type-defs.js
new file mode 100644
index 0000000000000..53c485d64e499
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/apollo/type-defs.js
@@ -0,0 +1,13 @@
+import { gql } from '@apollo/client'
+
+export const typeDefs = gql`
+ type User {
+ id: ID!
+ name: String!
+ status: String!
+ }
+
+ type Query {
+ viewer: User
+ }
+`
diff --git a/examples/api-routes-apollo-server-and-client/package.json b/examples/api-routes-apollo-server-and-client/package.json
new file mode 100644
index 0000000000000..8ac88860500d3
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/package.json
@@ -0,0 +1,18 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "@apollo/client": "^3.0.2",
+ "apollo-server-micro": "^2.14.2",
+ "deepmerge": "4.2.2",
+ "graphql": "^14.0.2",
+ "next": "latest",
+ "prop-types": "^15.6.2",
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
+ }
+}
diff --git a/examples/api-routes-apollo-server-and-client/pages/_app.js b/examples/api-routes-apollo-server-and-client/pages/_app.js
new file mode 100644
index 0000000000000..482728ae76e6d
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/pages/_app.js
@@ -0,0 +1,12 @@
+import { ApolloProvider } from '@apollo/client'
+import { useApollo } from '../apollo/client'
+
+export default function App({ Component, pageProps }) {
+ const apolloClient = useApollo(pageProps.initialApolloState)
+
+ return (
+
+
+
+ )
+}
diff --git a/examples/api-routes-apollo-server-and-client/pages/about.js b/examples/api-routes-apollo-server-and-client/pages/about.js
new file mode 100644
index 0000000000000..1a13743a81299
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/pages/about.js
@@ -0,0 +1,9 @@
+import Link from 'next/link'
+
+export default function About() {
+ return (
+
+ This is a static page goto dynamic page.
+
+ )
+}
diff --git a/examples/api-routes-apollo-server-and-client/pages/api/graphql.js b/examples/api-routes-apollo-server-and-client/pages/api/graphql.js
new file mode 100644
index 0000000000000..5efa800e28cd8
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/pages/api/graphql.js
@@ -0,0 +1,12 @@
+import { ApolloServer } from 'apollo-server-micro'
+import { schema } from '../../apollo/schema'
+
+const apolloServer = new ApolloServer({ schema })
+
+export const config = {
+ api: {
+ bodyParser: false,
+ },
+}
+
+export default apolloServer.createHandler({ path: '/api/graphql' })
diff --git a/examples/api-routes-apollo-server-and-client/pages/index.js b/examples/api-routes-apollo-server-and-client/pages/index.js
new file mode 100644
index 0000000000000..42b09c1c93d41
--- /dev/null
+++ b/examples/api-routes-apollo-server-and-client/pages/index.js
@@ -0,0 +1,43 @@
+import gql from 'graphql-tag'
+import Link from 'next/link'
+import { useQuery } from '@apollo/client'
+import { initializeApollo } from '../apollo/client'
+
+const ViewerQuery = gql`
+ query ViewerQuery {
+ viewer {
+ id
+ name
+ status
+ }
+ }
+`
+
+const Index = () => {
+ const {
+ data: { viewer },
+ } = useQuery(ViewerQuery)
+
+ return (
+
+ You're signed in as {viewer.name} and you're {viewer.status} goto{' '}
+ static page.
+
+ )
+}
+
+export async function getStaticProps() {
+ const apolloClient = initializeApollo()
+
+ await apolloClient.query({
+ query: ViewerQuery,
+ })
+
+ return {
+ props: {
+ initialApolloState: apolloClient.cache.extract(),
+ },
+ }
+}
+
+export default Index
diff --git a/examples/api-routes-apollo-server/.gitignore b/examples/api-routes-apollo-server/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/api-routes-apollo-server/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/api-routes-apollo-server/README.md b/examples/api-routes-apollo-server/README.md
new file mode 100644
index 0000000000000..4eca8668283cc
--- /dev/null
+++ b/examples/api-routes-apollo-server/README.md
@@ -0,0 +1,35 @@
+# Consume local Apollo GraphQL schema to create Static Generation export
+
+Next.js ships with two forms of pre-rendering: [Static Generation](https://nextjs.org/docs/basic-features/pages#static-generation-recommended) and [Server-side Rendering](https://nextjs.org/docs/basic-features/pages#server-side-rendering). This example shows how to perform Static Generation using a local [Apollo GraphQL](https://www.apollographql.com/docs/apollo-server/) schema within [getStaticProps](https://nextjs.org/docs/basic-features/data-fetching/get-static-props) and [getStaticPaths](https://nextjs.org/docs/basic-features/data-fetching/get-static-paths.md). The end result is a Next.js application that uses one Apollo GraphQL schema to generate static pages at build time and also serve a GraphQL [API Route](https://nextjs.org/docs/api-routes/introduction) at runtime.
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-apollo-server)
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-apollo-server&project-name=api-routes-apollo-server&repository-name=api-routes-apollo-server)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example api-routes-apollo-server api-routes-apollo-server-app
+```
+
+```bash
+yarn create next-app --example api-routes-apollo-server api-routes-apollo-server-app
+```
+
+```bash
+pnpm create next-app --example api-routes-apollo-server api-routes-apollo-server-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+
+## Notes
+
+### Static Export
+
+If you wish to export a static HTML + JS version of the site you need to first change the setting in this example in `./pages/[username].js` where `getStaticPaths` has `fallback: true` - this needs to be `false` for static export to work. You can then run `npm run build` and `npm run export` to export the site as a static folder in `./out` directory.
+
+[Read more about fallback option](https://nextjs.org/docs/basic-features/data-fetching#the-fallback-key-required)
diff --git a/examples/api-routes-apollo-server/package.json b/examples/api-routes-apollo-server/package.json
new file mode 100644
index 0000000000000..31c59e7798ddb
--- /dev/null
+++ b/examples/api-routes-apollo-server/package.json
@@ -0,0 +1,16 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "export": "next export",
+ "start": "next start"
+ },
+ "dependencies": {
+ "apollo-server-micro": "2.13.1",
+ "graphql": "15.0.0",
+ "next": "latest",
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
+ }
+}
diff --git a/examples/api-routes-apollo-server/pages/[username].js b/examples/api-routes-apollo-server/pages/[username].js
new file mode 100644
index 0000000000000..30f792c375ae2
--- /dev/null
+++ b/examples/api-routes-apollo-server/pages/[username].js
@@ -0,0 +1,45 @@
+import queryGraphql from '../shared/query-graphql'
+
+export default function UserProfile({ user }) {
+ if (!user) {
+ return
+ )
+}
+
+export async function getStaticProps() {
+ const { users } = await queryGraphql(`
+ query {
+ users {
+ name
+ username
+ }
+ }
+ `)
+ return { props: { users } }
+}
diff --git a/examples/api-routes-apollo-server/shared/query-graphql/index.js b/examples/api-routes-apollo-server/shared/query-graphql/index.js
new file mode 100644
index 0000000000000..9393dbf8f237c
--- /dev/null
+++ b/examples/api-routes-apollo-server/shared/query-graphql/index.js
@@ -0,0 +1,8 @@
+import { graphql } from 'graphql'
+
+import { schema } from '../../pages/api/graphql'
+
+export default async function queryGraphql(query, variableValues = {}) {
+ const { data } = await graphql({ schema, source: query, variableValues })
+ return data || {}
+}
diff --git a/examples/api-routes-cors/.gitignore b/examples/api-routes-cors/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/api-routes-cors/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/api-routes-cors/README.md b/examples/api-routes-cors/README.md
new file mode 100644
index 0000000000000..a8d148109a0d1
--- /dev/null
+++ b/examples/api-routes-cors/README.md
@@ -0,0 +1,29 @@
+# API Routes Example with CORS
+
+Next.js ships with [API routes](https://nextjs.org/docs/api-routes/introduction) which provides an easy solution to build your own `API`.
+
+This example shows how to create an `API` endpoint with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers, using the [cors](https://github.com/expressjs/cors) package.
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-cors)
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-cors&project-name=api-routes-cors&repository-name=api-routes-cors)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example api-routes-cors api-routes-cors-app
+```
+
+```bash
+yarn create next-app --example api-routes-cors api-routes-cors-app
+```
+
+```bash
+pnpm create next-app --example api-routes-cors api-routes-cors-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/api-routes-cors/package.json b/examples/api-routes-cors/package.json
new file mode 100644
index 0000000000000..0f1b8cf88f93e
--- /dev/null
+++ b/examples/api-routes-cors/package.json
@@ -0,0 +1,21 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "cors": "^2.8.5",
+ "next": "latest",
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
+ },
+ "devDependencies": {
+ "@types/cors": "^2.8.12",
+ "@types/node": "^18.0.1",
+ "@types/react": "^18.0.14",
+ "@types/react-dom": "^18.0.6",
+ "typescript": "^4.7.4"
+ }
+}
diff --git a/examples/api-routes-cors/pages/api/cors.ts b/examples/api-routes-cors/pages/api/cors.ts
new file mode 100644
index 0000000000000..8266295ff9165
--- /dev/null
+++ b/examples/api-routes-cors/pages/api/cors.ts
@@ -0,0 +1,37 @@
+import type { NextApiRequest, NextApiResponse } from 'next'
+import Cors from 'cors'
+
+// Initializing the cors middleware
+// You can read more about the available options here: https://github.com/expressjs/cors#configuration-options
+const cors = Cors({
+ methods: ['POST', 'GET', 'HEAD'],
+})
+
+// Helper method to wait for a middleware to execute before continuing
+// And to throw an error when an error happens in a middleware
+function runMiddleware(
+ req: NextApiRequest,
+ res: NextApiResponse,
+ fn: Function
+) {
+ return new Promise((resolve, reject) => {
+ fn(req, res, (result: any) => {
+ if (result instanceof Error) {
+ return reject(result)
+ }
+
+ return resolve(result)
+ })
+ })
+}
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ // Run the middleware
+ await runMiddleware(req, res, cors)
+
+ // Rest of the API logic
+ res.json({ message: 'Hello Everyone!' })
+}
diff --git a/examples/api-routes-cors/pages/index.tsx b/examples/api-routes-cors/pages/index.tsx
new file mode 100644
index 0000000000000..9506fde9d82f4
--- /dev/null
+++ b/examples/api-routes-cors/pages/index.tsx
@@ -0,0 +1,9 @@
+export default function Index() {
+ return (
+
+ To test the CORS route, open the console in a new tab on a different
+ domain and make a POST / GET / OPTIONS request to /api/cors. Using
+ a different method from those mentioned will be blocked by CORS
+
+ )
+}
diff --git a/examples/api-routes-cors/tsconfig.json b/examples/api-routes-cors/tsconfig.json
new file mode 100644
index 0000000000000..114d0ab4942b1
--- /dev/null
+++ b/examples/api-routes-cors/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true
+ },
+ "include": ["next-env.d.ts", "amp.d.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/api-routes-graphql/.gitignore b/examples/api-routes-graphql/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/api-routes-graphql/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/api-routes-graphql/README.md b/examples/api-routes-graphql/README.md
new file mode 100644
index 0000000000000..c52d1e3b3c305
--- /dev/null
+++ b/examples/api-routes-graphql/README.md
@@ -0,0 +1,44 @@
+# API routes with GraphQL server
+
+Next.js ships with [API routes](https://nextjs.org/docs/api-routes/introduction), which provide an easy solution to build your own `API`.
+This example showcases how to build a lightweight and blazing fast GraphQL API with minimum configuration using GraphQL Yoga.
+
+GraphQL Yoga comes with strong defaults:
+
+- CORS is enabled by default
+- Automatically masking unexpected errors and preventing sensitive information from leaking to clients.
+- Shipped with GraphiQL
+
+Yoga also brings support (with no additional dependency) for subscriptions, file uploads, and your favorite schema-building library (GraphQL Tools, Pothos, Nexus, TypeGraphQL, SDL first schema-design approaches, graphql-js, Apollo Tools).
+
+More information on all available features are available [on the official documentation](https://www.graphql-yoga.com/docs/quick-start).
+
+Finally, GraphQL Yoga is built on top of Envelop. Envelop is a library that helps build GraphQL API faster and flexibly with plugin-based architecture.
+
+Similar to Express middlewares allowing you to customize requests' behavior, Envelop applies the same idea to GraphQL requests.
+
+More information on [Envelop documentation](https://www.envelop.dev/).
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-graphql)
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-graphql&project-name=api-routes-graphql&repository-name=api-routes-graphql)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example api-routes-graphql api-routes-graphql-app
+```
+
+```bash
+yarn create next-app --example api-routes-graphql api-routes-graphql-app
+```
+
+```bash
+pnpm create next-app --example api-routes-graphql api-routes-graphql-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/api-routes-graphql/package.json b/examples/api-routes-graphql/package.json
new file mode 100644
index 0000000000000..b06243e07d643
--- /dev/null
+++ b/examples/api-routes-graphql/package.json
@@ -0,0 +1,22 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "graphql-yoga": "three",
+ "graphql": "^16.5.0",
+ "next": "latest",
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0",
+ "swr": "^1.3.0"
+ },
+ "devDependencies": {
+ "@types/node": "^18.0.2",
+ "@types/react": "^18.0.15",
+ "@types/react-dom": "^18.0.6",
+ "typescript": "^4.7.4"
+ }
+}
diff --git a/examples/api-routes-graphql/pages/api/graphql.ts b/examples/api-routes-graphql/pages/api/graphql.ts
new file mode 100644
index 0000000000000..14868f68ac7d8
--- /dev/null
+++ b/examples/api-routes-graphql/pages/api/graphql.ts
@@ -0,0 +1,29 @@
+import { createYoga, createSchema } from 'graphql-yoga'
+
+const typeDefs = /* GraphQL */ `
+ type Query {
+ users: [User!]!
+ }
+ type User {
+ name: String
+ }
+`
+
+const resolvers = {
+ Query: {
+ users() {
+ return [{ name: 'Nextjs' }]
+ },
+ },
+}
+
+const schema = createSchema({
+ typeDefs,
+ resolvers,
+})
+
+export default createYoga({
+ schema,
+ // Needed to be defined explicitly because our endpoint lives at a different path other than `/graphql`
+ graphqlEndpoint: '/api/graphql',
+})
diff --git a/examples/api-routes-graphql/pages/index.tsx b/examples/api-routes-graphql/pages/index.tsx
new file mode 100644
index 0000000000000..b06279fada828
--- /dev/null
+++ b/examples/api-routes-graphql/pages/index.tsx
@@ -0,0 +1,29 @@
+import useSWR from 'swr'
+
+const fetcher = (query: string) =>
+ fetch('/api/graphql', {
+ method: 'POST',
+ headers: {
+ 'Content-type': 'application/json',
+ },
+ body: JSON.stringify({ query }),
+ })
+ .then((res) => res.json())
+ .then((json) => json.data)
+
+export default function Index() {
+ const { data, error } = useSWR('{ users { name } }', fetcher)
+
+ if (error) return
Failed to load
+ if (!data) return
Loading...
+
+ const { users } = data
+
+ return (
+
+ {users.map((user: any, i: number) => (
+
{user.name}
+ ))}
+
+ )
+}
diff --git a/examples/api-routes-graphql/tsconfig.json b/examples/api-routes-graphql/tsconfig.json
new file mode 100644
index 0000000000000..b8d597880a1ae
--- /dev/null
+++ b/examples/api-routes-graphql/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true
+ },
+ "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/api-routes-middleware/.gitignore b/examples/api-routes-middleware/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/api-routes-middleware/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/api-routes-middleware/README.md b/examples/api-routes-middleware/README.md
new file mode 100644
index 0000000000000..a485ef2a6ae49
--- /dev/null
+++ b/examples/api-routes-middleware/README.md
@@ -0,0 +1,27 @@
+# API routes with middleware
+
+Next.js ships with [API routes](https://github.com/vercel/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows how to implement simple `middleware` to wrap around your `API` endpoints.
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-middleware)
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-middleware&project-name=api-routes-middleware&repository-name=api-routes-middleware)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example api-routes-middleware api-routes-middleware-app
+```
+
+```bash
+yarn create next-app --example api-routes-middleware api-routes-middleware-app
+```
+
+```bash
+pnpm create next-app --example api-routes-middleware api-routes-middleware-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/api-routes-middleware/package.json b/examples/api-routes-middleware/package.json
new file mode 100644
index 0000000000000..537e3660922f3
--- /dev/null
+++ b/examples/api-routes-middleware/package.json
@@ -0,0 +1,21 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "cookie": "^0.5.0",
+ "next": "latest",
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0",
+ "swr": "^1.3.0"
+ },
+ "devDependencies": {
+ "@types/node": "^18.0.2",
+ "@types/react": "^18.0.15",
+ "@types/react-dom": "^18.0.6",
+ "typescript": "^4.7.4"
+ }
+}
diff --git a/examples/api-routes-middleware/pages/api/cookies.ts b/examples/api-routes-middleware/pages/api/cookies.ts
new file mode 100644
index 0000000000000..2b43c280471fc
--- /dev/null
+++ b/examples/api-routes-middleware/pages/api/cookies.ts
@@ -0,0 +1,9 @@
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { setCookie } from '../../utils/cookies'
+
+export default function handler(_req: NextApiRequest, res: NextApiResponse) {
+ // Calling our pure function using the `res` object, it will add the `set-cookie` header
+ setCookie(res, 'Next.js', 'api-middleware!')
+ // Return the `set-cookie` header so we can display it in the browser and show that it works!
+ res.end(res.getHeader('Set-Cookie'))
+}
diff --git a/examples/api-routes-middleware/pages/index.tsx b/examples/api-routes-middleware/pages/index.tsx
new file mode 100644
index 0000000000000..51c784cc104a7
--- /dev/null
+++ b/examples/api-routes-middleware/pages/index.tsx
@@ -0,0 +1,12 @@
+import useSWR from 'swr'
+
+const fetcher = (url) => fetch(url).then((res) => res.text())
+
+export default function Index() {
+ const { data, error } = useSWR('/api/cookies', fetcher)
+
+ if (error) return
Failed to load
+ if (!data) return
Loading...
+
+ return
{`Cookie from response: "${data}"`}
+}
diff --git a/examples/api-routes-middleware/tsconfig.json b/examples/api-routes-middleware/tsconfig.json
new file mode 100644
index 0000000000000..b8d597880a1ae
--- /dev/null
+++ b/examples/api-routes-middleware/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true
+ },
+ "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/api-routes-middleware/utils/cookies.ts b/examples/api-routes-middleware/utils/cookies.ts
new file mode 100644
index 0000000000000..fffe89978f6bd
--- /dev/null
+++ b/examples/api-routes-middleware/utils/cookies.ts
@@ -0,0 +1,22 @@
+import type { NextApiResponse } from 'next'
+import { serialize, CookieSerializeOptions } from 'cookie'
+
+/**
+ * This sets `cookie` using the `res` object
+ */
+
+export const setCookie = (
+ res: NextApiResponse,
+ name: string,
+ value: unknown,
+ options: CookieSerializeOptions = {}
+) => {
+ const stringValue =
+ typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value)
+
+ if (typeof options.maxAge === 'number') {
+ options.expires = new Date(Date.now() + options.maxAge * 1000)
+ }
+
+ res.setHeader('Set-Cookie', serialize(name, stringValue, options))
+}
diff --git a/examples/api-routes-rate-limit/.gitignore b/examples/api-routes-rate-limit/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/api-routes-rate-limit/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/api-routes-rate-limit/README.md b/examples/api-routes-rate-limit/README.md
new file mode 100644
index 0000000000000..1868916bc6242
--- /dev/null
+++ b/examples/api-routes-rate-limit/README.md
@@ -0,0 +1,41 @@
+# API Routes Rate Limiting Example
+
+This example uses `lru-cache` to implement a simple rate limiter for API routes ([Serverless Functions](https://vercel.com/docs/serverless-functions/introduction)).
+
+**Demo: https://nextjs-rate-limit.vercel.app/**
+
+```bash
+curl http://localhost:3000/api/user -I
+HTTP/1.1 200 OK
+X-RateLimit-Limit: 10
+X-RateLimit-Remaining: 9
+
+curl http://localhost:3000/api/user -I
+HTTP/1.1 429 Too Many Requests
+X-RateLimit-Limit: 10
+X-RateLimit-Remaining: 0
+```
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-rate-limit)
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-rate-limit&project-name=api-routes-rate-limit&repository-name=api-routes-rate-limit)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example api-routes-rate-limit api-routes-rate-limit-app
+```
+
+```bash
+yarn create next-app --example api-routes-rate-limit api-routes-rate-limit-app
+```
+
+```bash
+pnpm create next-app --example api-routes-rate-limit api-routes-rate-limit-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/api-routes-rate-limit/package.json b/examples/api-routes-rate-limit/package.json
new file mode 100644
index 0000000000000..1b5fec4ace47a
--- /dev/null
+++ b/examples/api-routes-rate-limit/package.json
@@ -0,0 +1,22 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "lru-cache": "^7.12.0",
+ "next": "latest",
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0",
+ "uuid": "^8.3.2"
+ },
+ "devDependencies": {
+ "@types/node": "^18.0.3",
+ "@types/react": "^18.0.15",
+ "@types/react-dom": "^18.0.6",
+ "@types/uuid": "^8.3.4",
+ "typescript": "^4.7.4"
+ }
+}
diff --git a/examples/api-routes-rate-limit/pages/api/user.ts b/examples/api-routes-rate-limit/pages/api/user.ts
new file mode 100644
index 0000000000000..ff3f446476961
--- /dev/null
+++ b/examples/api-routes-rate-limit/pages/api/user.ts
@@ -0,0 +1,20 @@
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { v4 as uuidv4 } from 'uuid'
+import rateLimit from '../../utils/rate-limit'
+
+const limiter = rateLimit({
+ interval: 60 * 1000, // 60 seconds
+ uniqueTokenPerInterval: 500, // Max 500 users per second
+})
+
+export default async function handler(
+ _req: NextApiRequest,
+ res: NextApiResponse
+) {
+ try {
+ await limiter.check(res, 10, 'CACHE_TOKEN') // 10 requests per minute
+ res.status(200).json({ id: uuidv4() })
+ } catch {
+ res.status(429).json({ error: 'Rate limit exceeded' })
+ }
+}
diff --git a/examples/api-routes-rate-limit/pages/index.tsx b/examples/api-routes-rate-limit/pages/index.tsx
new file mode 100644
index 0000000000000..5de685d4c7bbc
--- /dev/null
+++ b/examples/api-routes-rate-limit/pages/index.tsx
@@ -0,0 +1,34 @@
+import { useState } from 'react'
+import styles from '../styles.module.css'
+
+export default function Index() {
+ const [response, setResponse] = useState | null>(null)
+
+ const makeRequest = async () => {
+ const res = await fetch('/api/user')
+
+ setResponse({
+ status: res.status,
+ body: await res.json(),
+ limit: res.headers.get('X-RateLimit-Limit'),
+ remaining: res.headers.get('X-RateLimit-Remaining'),
+ })
+ }
+
+ return (
+
+
Next.js API Routes Rate Limiting
+
+ This example uses lru-cache{' '}
+ to implement a simple rate limiter for API routes (Serverless
+ Functions).
+
+
+ {response && (
+
+
{JSON.stringify(response, null, 2)}
+
+ )}
+
+ )
+}
diff --git a/examples/api-routes-rate-limit/styles.module.css b/examples/api-routes-rate-limit/styles.module.css
new file mode 100644
index 0000000000000..f2cd0c79e7de7
--- /dev/null
+++ b/examples/api-routes-rate-limit/styles.module.css
@@ -0,0 +1,67 @@
+.container {
+ padding: 4rem 1rem;
+ max-width: 50rem;
+ margin: 0 auto;
+ font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+ text-rendering: optimizeLegibility;
+ -webkit-font-smoothing: antialiased;
+ -moz-osx-font-smoothing: grayscale;
+}
+
+.container h1 {
+ font-weight: 800;
+}
+
+.container p {
+ margin: 1.5rem 0;
+ line-height: 1.5;
+}
+
+.container button {
+ border-radius: 4px;
+ height: 40px;
+ padding: 0.5rem 1rem;
+ font-size: 16px;
+ border: none;
+ transition: 0.25s all ease;
+ background-color: #eaeaea;
+ font-size: 14px;
+ font-weight: 600;
+ color: #111;
+}
+
+.container button:hover {
+ box-shadow: 0 5px 10px rgba(0, 0, 0, 0.12);
+}
+
+.container a {
+ text-decoration: none;
+ color: #0070f3;
+}
+
+.inlineCode {
+ color: #be00ff;
+ font-size: 16px;
+ white-space: pre-wrap;
+}
+
+.inlineCode::before,
+.inlineCode::after {
+ content: '`';
+}
+
+.code {
+ margin-top: 16px;
+ display: block;
+ background: #222222;
+ border-radius: 8px;
+ padding: 16px;
+ color: white;
+ font-size: 16px;
+ line-height: 1.4;
+}
+
+.links {
+ margin-top: 16px;
+ color: #9c9c9c;
+}
diff --git a/examples/api-routes-rate-limit/tsconfig.json b/examples/api-routes-rate-limit/tsconfig.json
new file mode 100644
index 0000000000000..b8d597880a1ae
--- /dev/null
+++ b/examples/api-routes-rate-limit/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true
+ },
+ "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/api-routes-rate-limit/utils/rate-limit.ts b/examples/api-routes-rate-limit/utils/rate-limit.ts
new file mode 100644
index 0000000000000..929230335260a
--- /dev/null
+++ b/examples/api-routes-rate-limit/utils/rate-limit.ts
@@ -0,0 +1,35 @@
+import type { NextApiResponse } from 'next'
+import LRU from 'lru-cache'
+
+type Options = {
+ uniqueTokenPerInterval?: number
+ interval?: number
+}
+
+export default function rateLimit(options?: Options) {
+ const tokenCache = new LRU({
+ max: options?.uniqueTokenPerInterval || 500,
+ ttl: options?.interval || 60000,
+ })
+
+ return {
+ check: (res: NextApiResponse, limit: number, token: string) =>
+ new Promise((resolve, reject) => {
+ const tokenCount = (tokenCache.get(token) as number[]) || [0]
+ if (tokenCount[0] === 0) {
+ tokenCache.set(token, tokenCount)
+ }
+ tokenCount[0] += 1
+
+ const currentUsage = tokenCount[0]
+ const isRateLimited = currentUsage >= limit
+ res.setHeader('X-RateLimit-Limit', limit)
+ res.setHeader(
+ 'X-RateLimit-Remaining',
+ isRateLimited ? 0 : limit - currentUsage
+ )
+
+ return isRateLimited ? reject() : resolve()
+ }),
+ }
+}
diff --git a/examples/api-routes-rest/.gitignore b/examples/api-routes-rest/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/api-routes-rest/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/api-routes-rest/README.md b/examples/api-routes-rest/README.md
new file mode 100644
index 0000000000000..f6d2af9432529
--- /dev/null
+++ b/examples/api-routes-rest/README.md
@@ -0,0 +1,29 @@
+# API routes with REST
+
+Next.js ships with [API routes](https://github.com/vercel/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows how it can be used to create your [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) `API`.
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes-rest)
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes-rest&project-name=api-routes-rest&repository-name=api-routes-rest)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example api-routes-rest api-routes-rest-app
+```
+
+```bash
+yarn create next-app --example api-routes-rest api-routes-rest-app
+```
+
+```bash
+pnpm create next-app --example api-routes-rest api-routes-rest-app
+```
+
+### Deploy to Vercel
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/api-routes-rest/interfaces/index.ts b/examples/api-routes-rest/interfaces/index.ts
new file mode 100644
index 0000000000000..6ea90ddd5385f
--- /dev/null
+++ b/examples/api-routes-rest/interfaces/index.ts
@@ -0,0 +1,4 @@
+export type User = {
+ id: number
+ name?: string
+}
diff --git a/examples/api-routes-rest/package.json b/examples/api-routes-rest/package.json
new file mode 100644
index 0000000000000..31ed2512a68c2
--- /dev/null
+++ b/examples/api-routes-rest/package.json
@@ -0,0 +1,20 @@
+{
+ "private": true,
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "next": "latest",
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0",
+ "swr": "^1.3.0"
+ },
+ "devDependencies": {
+ "@types/node": "^18.0.3",
+ "@types/react": "^18.0.15",
+ "@types/react-dom": "^18.0.6",
+ "typescript": "^4.7.4"
+ }
+}
diff --git a/examples/api-routes-rest/pages/api/user/[id].ts b/examples/api-routes-rest/pages/api/user/[id].ts
new file mode 100644
index 0000000000000..30942cf4e3919
--- /dev/null
+++ b/examples/api-routes-rest/pages/api/user/[id].ts
@@ -0,0 +1,22 @@
+import type { NextApiRequest, NextApiResponse } from 'next'
+
+export default function userHandler(req: NextApiRequest, res: NextApiResponse) {
+ const {
+ query: { id, name },
+ method,
+ } = req
+
+ switch (method) {
+ case 'GET':
+ // Get data from your database
+ res.status(200).json({ id, name: `User ${id}` })
+ break
+ case 'PUT':
+ // Update or create data in your database
+ res.status(200).json({ id, name: name || `User ${id}` })
+ break
+ default:
+ res.setHeader('Allow', ['GET', 'PUT'])
+ res.status(405).end(`Method ${method} Not Allowed`)
+ }
+}
diff --git a/examples/api-routes-rest/pages/api/users.ts b/examples/api-routes-rest/pages/api/users.ts
new file mode 100644
index 0000000000000..238c5c55366c1
--- /dev/null
+++ b/examples/api-routes-rest/pages/api/users.ts
@@ -0,0 +1,10 @@
+import type { NextApiRequest, NextApiResponse } from 'next'
+import type { User } from '../../interfaces'
+
+// Fake users data
+const users: User[] = [{ id: 1 }, { id: 2 }, { id: 3 }]
+
+export default function handler(_req: NextApiRequest, res: NextApiResponse) {
+ // Get data from your database
+ res.status(200).json(users)
+}
diff --git a/examples/api-routes-rest/pages/index.tsx b/examples/api-routes-rest/pages/index.tsx
new file mode 100644
index 0000000000000..15b852db3568c
--- /dev/null
+++ b/examples/api-routes-rest/pages/index.tsx
@@ -0,0 +1,24 @@
+import type { User } from '../interfaces'
+import useSwr from 'swr'
+import Link from 'next/link'
+
+const fetcher = (url: string) => fetch(url).then((res) => res.json())
+
+export default function Index() {
+ const { data, error } = useSwr('/api/users', fetcher)
+
+ if (error) return
Failed to load users
+ if (!data) return
Loading...
+
+ return (
+
+ {data.map((user) => (
+
+
+ {`User ${user.id}`}
+
+
+ ))}
+
+ )
+}
diff --git a/examples/api-routes-rest/pages/user/[id].tsx b/examples/api-routes-rest/pages/user/[id].tsx
new file mode 100644
index 0000000000000..d348ead17b9a1
--- /dev/null
+++ b/examples/api-routes-rest/pages/user/[id].tsx
@@ -0,0 +1,18 @@
+import type { User } from '../../interfaces'
+import { useRouter } from 'next/router'
+import useSwr from 'swr'
+
+const fetcher = (url: string) => fetch(url).then((res) => res.json())
+
+export default function UserPage() {
+ const router = useRouter()
+ const { data, error } = useSwr(
+ router.query.id ? `/api/user/${router.query.id}` : null,
+ fetcher
+ )
+
+ if (error) return
Failed to load user
+ if (!data) return
Loading...
+
+ return
{data.name}
+}
diff --git a/examples/api-routes-rest/tsconfig.json b/examples/api-routes-rest/tsconfig.json
new file mode 100644
index 0000000000000..b8d597880a1ae
--- /dev/null
+++ b/examples/api-routes-rest/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true
+ },
+ "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/api-routes/.gitignore b/examples/api-routes/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/api-routes/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/api-routes/README.md b/examples/api-routes/README.md
new file mode 100644
index 0000000000000..fb7fcd1822730
--- /dev/null
+++ b/examples/api-routes/README.md
@@ -0,0 +1,27 @@
+# Basic API routes example
+
+Next.js ships with [API routes](https://nextjs.org/docs/api-routes/introduction) which provides an easy solution to build your own `API`. This example shows how to create multiple `API` endpoints with serverless functions, which can execute independently.
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/api-routes)
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/api-routes&project-name=api-routes&repository-name=api-routes)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example api-routes api-routes-app
+```
+
+```bash
+yarn create next-app --example api-routes api-routes-app
+```
+
+```bash
+pnpm create next-app --example api-routes api-routes-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/api-routes/components/Person.tsx b/examples/api-routes/components/Person.tsx
new file mode 100644
index 0000000000000..1925bb0bfcbae
--- /dev/null
+++ b/examples/api-routes/components/Person.tsx
@@ -0,0 +1,16 @@
+import Link from 'next/link'
+import { Person } from '../interfaces'
+
+type PersonProps = {
+ person: Person
+}
+
+export default function PersonComponent({ person }: PersonProps) {
+ return (
+
+ )
+}
diff --git a/examples/api-routes/pages/person/[id].tsx b/examples/api-routes/pages/person/[id].tsx
new file mode 100644
index 0000000000000..11d5d0cbcbb3d
--- /dev/null
+++ b/examples/api-routes/pages/person/[id].tsx
@@ -0,0 +1,50 @@
+import { useRouter } from 'next/router'
+import useSWR from 'swr'
+
+const fetcher = async (url: string) => {
+ const res = await fetch(url)
+ const data = await res.json()
+
+ if (res.status !== 200) {
+ throw new Error(data.message)
+ }
+ return data
+}
+
+export default function Person() {
+ const { query } = useRouter()
+ const { data, error } = useSWR(
+ () => query.id && `/api/people/${query.id}`,
+ fetcher
+ )
+
+ if (error) return
{error.message}
+ if (!data) return
Loading...
+
+ return (
+
+
+
+
Name
+
Height
+
Mass
+
Hair color
+
Skin color
+
Eye color
+
Gender
+
+
+
+
+
{data.name}
+
{data.height}
+
{data.mass}
+
{data.hair_color}
+
{data.skin_color}
+
{data.eye_color}
+
{data.gender}
+
+
+
+ )
+}
diff --git a/examples/api-routes/tsconfig.json b/examples/api-routes/tsconfig.json
new file mode 100644
index 0000000000000..b8d597880a1ae
--- /dev/null
+++ b/examples/api-routes/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true
+ },
+ "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/auth-with-stytch/.env.template b/examples/auth-with-stytch/.env.template
new file mode 100644
index 0000000000000..4aed8e797e320
--- /dev/null
+++ b/examples/auth-with-stytch/.env.template
@@ -0,0 +1,8 @@
+# The two iron-session values may be left as-is while testing out this example app.
+IRON_SESSION_COOKIE_NAME="stytch_next_example_cookie"
+IRON_SESSION_PASSWORD="complex_password_at_least_32_characters_long"
+# The below values may be found in your Stytch Dashboard: https://stytch.com/dashboard/api-keys
+STYTCH_PROJECT_ENV=test
+STYTCH_PROJECT_ID="YOUR_STYTCH_PROJECT_ID"
+STYTCH_SECRET="YOUR_STYTCH_SECRET"
+NEXT_PUBLIC_STYTCH_PUBLIC_TOKEN="YOUR_STYTCH_PUBLIC_TOKEN"
diff --git a/examples/auth-with-stytch/.gitignore b/examples/auth-with-stytch/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/auth-with-stytch/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/auth-with-stytch/README.md b/examples/auth-with-stytch/README.md
new file mode 100644
index 0000000000000..7d787948b5236
--- /dev/null
+++ b/examples/auth-with-stytch/README.md
@@ -0,0 +1,68 @@
+# Stytch + Next.js example app on Vercel
+
+This is a [Stytch](https://stytch.com) + [Next.js](https://nextjs.org/) project that showcases how to enable elegant authentication in your applicaiton.
+
+
+
+In this repo, we have two sample auth flows:
+
+- SDK integration: This flow uses Stytch's React component to create a login and sign-up flow using [Email Magic Links](https://stytch.com/docs/api/send-by-email).
+- API integration: This flow uses a custom UI with Stytch's backend API for [Onetime Passcodes(OTP) via SMS](https://stytch.com/docs/api/sms-otp-overview) authentication.
+
+Both flows use Stytch's [Node client library](https://github.com/stytchauth/stytch-node) and [`iron-session`](https://github.com/vvo/next-iron-session) for session management.
+
+**Note:** By default this example app enables three of our OAuth providers, Google, Microsoft, and Apple. If you haven't set up these OAuth providers in your [Dashboard](https://stytch.com/dashboard/oauth), you'll receive a redirect error when you attempt to login via those providers. You may remove all OAuth methods by removing `SDKProductTypes.oauth` from the `products` array in [pages/index.tsx](pages/index.tsx) or adjust which ones are displayed by via `oauthOptions.providers` in the same file. More detail on working with OAuth providers in our SDK may be found in our [Docs](https://stytch.com/docs/javascript-sdk#javascript-sdk/oauth).
+
+# Deploy on Vercel
+
+## Setting up Stytch
+
+The first step is to configure the appropriate redirect URLs for your project. You'll set these magic link redirect URLs in the [Redirect URLs](https://stytch.com/dashboard/redirect-urls) section of your Dashboard. Add `https://*.vercel.app:3000` as both a login and sign-up redirect URL.
+
+## Running the example app
+
+Now just click the deploy button below! Once you're signed in to your Vercel account, you'll be guided through how to get up and running quickly. Check out [.env.template](/.env.template) for pointers on filling in the appropriate environment variables for this step.
+
+[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Fblob%2Fcanary%2Fexamples%2Fauth-with-stytch%2F&env=STYTCH_PROJECT_ENV,STYTCH_PROJECT_ID,STYTCH_SECRET,NEXT_PUBLIC_STYTCH_PUBLIC_TOKEN,IRON_SESSION_PASSWORD,IRON_SESSION_COOKIE_NAME&envDescription=All%20variables%20here%20need%20values%2C%20see%20the%20following%20link%20for%20pointers%20on%20how%20to%20feel%20these%20out.&envLink=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Fblob%2Fcanary%2Fexamples%2Fauth-with-stytch%2F.env.template&project-name=stytch-nextjs-vercel&repo-name=stytch-nextjs-vercel&demo-title=Stytch%20on%20Next.js%20with%20Vercel&demo-description=Next.js%20example%20app%20using%20Stytch%20authentication&demo-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Fblob%2Fcanary%2Fexamples%2Fauth-with-stytch&demo-image=https%3A%2F%2Fstytch.com%2Flogo-preview.png)
+
+# Running locally via `vercel dev`
+
+## Setting up Stytch
+
+After signing up for Stytch, you'll need your Project's `project_id`, `secret`, and `public_token`. You can find these in the [API keys tab](https://stytch.com/dashboard/api-keys).
+
+Once you've gathered these values, add them to a new .env.local file.
+Example:
+
+```bash
+cp .env.template .env.local
+# Replace your keys in new .env.local file
+```
+
+Next we'll configure the appropriate redirect URLs for your project, you'll set these magic link URLs for your project in the [Redirect URLs](https://stytch.com/dashboard/redirect-urls) section of your Dashboard. Add `http://localhost:3000/api/authenticate_magic_link` as both a login and sign-up redirect URL.
+
+## Running the example app
+
+Install dependencies by running
+
+```bash
+npm install
+# or
+yarn install
+```
+
+You can then run a development server using:
+
+```bash
+vercel dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+## Documentation
+
+Learn more about some of Stytch's products used in this example app:
+
+- [Stytch React](https://www.npmjs.com/package/@stytch/stytch-react)
+- [Stytch's node client library](https://www.npmjs.com/package/stytch)
+- [iron-session](https://github.com/vvo/next-iron-session)
diff --git a/examples/auth-with-stytch/components/LoginEntryPoint.tsx b/examples/auth-with-stytch/components/LoginEntryPoint.tsx
new file mode 100644
index 0000000000000..a8bf3562dca25
--- /dev/null
+++ b/examples/auth-with-stytch/components/LoginEntryPoint.tsx
@@ -0,0 +1,35 @@
+import React from 'react'
+import styles from '../styles/Home.module.css'
+import { LoginMethod } from '../lib/types'
+import StytchContainer from './StytchContainer'
+
+type Props = {
+ setLoginMethod: (loginMethod: LoginMethod) => void
+}
+
+const LoginEntryPoint = (props: Props) => {
+ const { setLoginMethod } = props
+ return (
+
+
Hello Vercel!
+
+ This example app demonstrates how you can integrate with Stytch using
+ Next.js and deploy on Vercel. Now, let’s get started!
+
+ This project shows different ways to display Profile info: using{' '}
+ Client rendered, Server rendered, and API rendered
+
+
+ Navigating between this page and Home is always pretty fast.
+ However, when you navigate to the Server rendered profile page it
+ takes more time because it uses SSR to fetch the user and then to
+ display it
+
By making request to '/api/protected-api' serverless function
+
so without a valid session cookie will fail
+
{JSON.stringify(data)}
+
+
+ )
+}
+
+// Public route.(CSR) also accessing API from the client-side.
+// data is not cached when redirecting between pages.
+export default ApiProfile
diff --git a/examples/auth0/pages/advanced/ssr-profile.tsx b/examples/auth0/pages/advanced/ssr-profile.tsx
new file mode 100644
index 0000000000000..298b890db17dd
--- /dev/null
+++ b/examples/auth0/pages/advanced/ssr-profile.tsx
@@ -0,0 +1,26 @@
+import { withPageAuthRequired } from '@auth0/nextjs-auth0'
+import Layout from '../../components/layout'
+import { User } from '../../interfaces'
+
+type ProfileProps = {
+ user: User
+}
+
+export default function Profile({ user }: ProfileProps) {
+ return (
+
+
Profile
+
+
+
Profile (server rendered)
+
+
nickname: {user.nickname}
+
name: {user.name}
+
+
+ )
+}
+
+// Protected route, checking authentication status before rendering the page.(SSR)
+// It's slower than a static page with client side authentication
+export const getServerSideProps = withPageAuthRequired()
diff --git a/examples/auth0/pages/api/auth/[...auth0].tsx b/examples/auth0/pages/api/auth/[...auth0].tsx
new file mode 100644
index 0000000000000..1edbfe3eb472d
--- /dev/null
+++ b/examples/auth0/pages/api/auth/[...auth0].tsx
@@ -0,0 +1,3 @@
+import { handleAuth } from '@auth0/nextjs-auth0'
+
+export default handleAuth()
diff --git a/examples/auth0/pages/api/protected-api.ts b/examples/auth0/pages/api/protected-api.ts
new file mode 100644
index 0000000000000..a2d6a95720cd7
--- /dev/null
+++ b/examples/auth0/pages/api/protected-api.ts
@@ -0,0 +1,20 @@
+import { withApiAuthRequired, getSession } from '@auth0/nextjs-auth0'
+
+// Serverless function
+// Protected API, requests to '/api/protected' without a valid session cookie will fail
+
+async function handle(req, res) {
+ const { user } = getSession(req, res)
+
+ try {
+ res.status(200).json({
+ session: 'true',
+ id: user.sub,
+ nickname: user.nickname,
+ })
+ } catch (e) {
+ res.status(500).json({ error: 'Unable to fetch', description: e })
+ }
+}
+
+export default withApiAuthRequired(handle)
diff --git a/examples/auth0/pages/index.tsx b/examples/auth0/pages/index.tsx
new file mode 100644
index 0000000000000..a184ac9fb6444
--- /dev/null
+++ b/examples/auth0/pages/index.tsx
@@ -0,0 +1,39 @@
+import { useUser } from '@auth0/nextjs-auth0'
+import Layout from '../components/layout'
+
+const Home = () => {
+ const { user, isLoading } = useUser()
+
+ return (
+
+
Next.js and Auth0 Example
+
+ {isLoading &&
Loading login info...
}
+
+ {!isLoading && !user && (
+ <>
+
+ To test the login click in Login
+
+
+ Once you have logged in you should be able to navigate between
+ protected routes: client rendered, server rendered profile pages,
+ and Logout
+
+
+ )}
+
+ {user && (
+ <>
+
Rendered user info on the client
+
+
nickname: {user.nickname}
+
name: {user.name}
+
+ )}
+
+ )
+}
+
+// fast/cached SSR page
+export default Home
diff --git a/examples/auth0/pages/profile.tsx b/examples/auth0/pages/profile.tsx
new file mode 100644
index 0000000000000..9e83595b6b55d
--- /dev/null
+++ b/examples/auth0/pages/profile.tsx
@@ -0,0 +1,33 @@
+import { withPageAuthRequired } from '@auth0/nextjs-auth0'
+import Layout from '../components/layout'
+import { User } from '../interfaces'
+
+type ProfileCardProps = {
+ user: User
+}
+
+const ProfileCard = ({ user }: ProfileCardProps) => {
+ return (
+ <>
+
Profile
+
+
+
Profile (client rendered)
+
+
nickname: {user.nickname}
+
name: {user.name}
+
+
+ )
+}
+
+const Profile = ({ user, isLoading }) => {
+ return (
+
+ {isLoading ? <>Loading... : }
+
+ )
+}
+
+// Protected route, checking user authentication client-side.(CSR)
+export default withPageAuthRequired(Profile)
diff --git a/examples/auth0/tsconfig.json b/examples/auth0/tsconfig.json
new file mode 100644
index 0000000000000..ef98c53d98df7
--- /dev/null
+++ b/examples/auth0/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true
+ },
+ "include": ["next-env.d.ts", "additional.d.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/authsignal/passwordless-login/.env.local.example b/examples/authsignal/passwordless-login/.env.local.example
new file mode 100644
index 0000000000000..61ecc44b3252a
--- /dev/null
+++ b/examples/authsignal/passwordless-login/.env.local.example
@@ -0,0 +1,3 @@
+AUTHSIGNAL_SECRET=
+SESSION_TOKEN_SECRET=
+REDIRECT_URL=http://localhost:3000/api/finalize-login
diff --git a/examples/authsignal/passwordless-login/.gitignore b/examples/authsignal/passwordless-login/.gitignore
new file mode 100755
index 0000000000000..46f26a804bbe1
--- /dev/null
+++ b/examples/authsignal/passwordless-login/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
\ No newline at end of file
diff --git a/examples/authsignal/passwordless-login/README.md b/examples/authsignal/passwordless-login/README.md
new file mode 100755
index 0000000000000..2acdf21af43ba
--- /dev/null
+++ b/examples/authsignal/passwordless-login/README.md
@@ -0,0 +1,45 @@
+# Authsignal Passwordless Login Example
+
+This example shows how to integrate Authsignal with Next.js in order to implement passwordless login using email magic links and server-side redirects.
+
+The login session is managed using cookies. Session data is encrypted using [@hapi/iron](https://hapi.dev/family/iron).
+
+A live version of this example can be found [here](https://authsignal-next-passwordless-example.vercel.app).
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/authsignal-passwordless&project-name=authsignal-passwordless&repository-name=authsignal-passwordless)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example authsignal-passwordless authsignal-passwordless-app
+# or
+yarn create next-app --example authsignal-passwordless authsignal-passwordless-app
+# or
+pnpm create next-app --example authsignal-passwordless authsignal-passwordless-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+
+## Configuration
+
+Log in to the [Authsignal Portal](https://portal.authsignal.com) and [enable email magic links for your tenant](https://portal.authsignal.com/organisations/tenants/authenticators).
+
+Copy the .env.local.example file to .env.local:
+
+```
+cp .env.local.example .env.local
+```
+
+Set `AUTHSIGNAL_SECRET` as your [Authsignal secret key](https://portal.authsignal.com/organisations/tenants/api).
+
+The `SESSION_TOKEN_SECRET` is used to encrypt the session cookie. Set it to a random string of 32 characters.
+
+## Notes
+
+To learn more about Authsignal take a look at the [API Documentation](https://docs.authsignal.com/).
diff --git a/examples/authsignal/passwordless-login/components/dashboard.module.css b/examples/authsignal/passwordless-login/components/dashboard.module.css
new file mode 100644
index 0000000000000..e2cfe5f3c758f
--- /dev/null
+++ b/examples/authsignal/passwordless-login/components/dashboard.module.css
@@ -0,0 +1,38 @@
+.header {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ background-color: #1d1d1d;
+ width: 100%;
+}
+
+.header button {
+ cursor: pointer;
+ font-size: 13px;
+ font-weight: 500;
+ line-height: 1;
+ border: none;
+ background: none;
+ color: #fff;
+ padding: 15px;
+ transition: background-color 0.15s, color 0.15s;
+}
+
+.user {
+ display: flex;
+ justify-content: center;
+ align-items: center;
+ flex-direction: column;
+ flex-grow: 1;
+}
+
+.label {
+ font-size: 12px;
+ margin-bottom: 5px;
+}
+
+.logo {
+ font-size: 18px;
+ margin: 15px;
+ color: #fff;
+}
diff --git a/examples/authsignal/passwordless-login/components/dashboard.tsx b/examples/authsignal/passwordless-login/components/dashboard.tsx
new file mode 100644
index 0000000000000..b7a5a7051a4ae
--- /dev/null
+++ b/examples/authsignal/passwordless-login/components/dashboard.tsx
@@ -0,0 +1,35 @@
+import { useRouter } from 'next/router'
+import { User } from '../lib'
+import styles from './dashboard.module.css'
+
+interface Props {
+ user: User
+}
+
+export const Dashboard = ({ user }: Props) => {
+ const router = useRouter()
+
+ const logout = async () => {
+ await fetch('/api/logout', {
+ method: 'POST',
+ credentials: 'same-origin',
+ })
+
+ router.push('/')
+ }
+
+ return (
+ <>
+
+
-)
diff --git a/examples/basic-export/pages/index.tsx b/examples/basic-export/pages/index.tsx
new file mode 100644
index 0000000000000..5fd2c4f1d665d
--- /dev/null
+++ b/examples/basic-export/pages/index.tsx
@@ -0,0 +1,11 @@
+import Link from 'next/link'
+
+const Home = () => {
+ return (
+
+ Hello World. About
+
+ )
+}
+
+export default Home
diff --git a/examples/basic-export/tsconfig.json b/examples/basic-export/tsconfig.json
new file mode 100644
index 0000000000000..b8d597880a1ae
--- /dev/null
+++ b/examples/basic-export/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "es5",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true
+ },
+ "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/examples/blog-starter-typescript/README.md b/examples/blog-starter-typescript/README.md
new file mode 100644
index 0000000000000..8332c4020c6cd
--- /dev/null
+++ b/examples/blog-starter-typescript/README.md
@@ -0,0 +1,3 @@
+## Deprecated
+
+The main [blog-starter](/examples/blog-starter) example has been refactored to use TypeScript, so this example is deprecated.
diff --git a/examples/blog-starter/.gitignore b/examples/blog-starter/.gitignore
new file mode 100644
index 0000000000000..c87c9b392c020
--- /dev/null
+++ b/examples/blog-starter/.gitignore
@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/examples/blog-starter/@types/remark-html.d.ts b/examples/blog-starter/@types/remark-html.d.ts
new file mode 100644
index 0000000000000..e1b76b54f7e1e
--- /dev/null
+++ b/examples/blog-starter/@types/remark-html.d.ts
@@ -0,0 +1 @@
+declare module 'remark-html'
diff --git a/examples/blog-starter/README.md b/examples/blog-starter/README.md
new file mode 100644
index 0000000000000..7a54468c56abc
--- /dev/null
+++ b/examples/blog-starter/README.md
@@ -0,0 +1,63 @@
+# A statically generated blog example using Next.js, Markdown, and TypeScript
+
+This is the existing [blog-starter](https://github.com/vercel/next.js/tree/canary/examples/blog-starter) plus TypeScript.
+
+This example showcases Next.js's [Static Generation](https://nextjs.org/docs/basic-features/pages) feature using Markdown files as the data source.
+
+The blog posts are stored in `/_posts` as Markdown files with front matter support. Adding a new Markdown file in there will create a new blog post.
+
+To create the blog posts we use [`remark`](https://github.com/remarkjs/remark) and [`remark-html`](https://github.com/remarkjs/remark-html) to convert the Markdown files into an HTML string, and then send it down as a prop to the page. The metadata of every post is handled by [`gray-matter`](https://github.com/jonschlinkert/gray-matter) and also sent in props to the page.
+
+## Demo
+
+[https://next-blog-starter.vercel.app/](https://next-blog-starter.vercel.app/)
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/blog-starter)
+
+[](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/blog-starter&project-name=blog-starter&repository-name=blog-starter)
+
+### Related examples
+
+- [WordPress](/examples/cms-wordpress)
+- [DatoCMS](/examples/cms-datocms)
+- [Sanity](/examples/cms-sanity)
+- [TakeShape](/examples/cms-takeshape)
+- [Prismic](/examples/cms-prismic)
+- [Contentful](/examples/cms-contentful)
+- [Strapi](/examples/cms-strapi)
+- [Agility CMS](/examples/cms-agilitycms)
+- [Cosmic](/examples/cms-cosmic)
+- [ButterCMS](/examples/cms-buttercms)
+- [Storyblok](/examples/cms-storyblok)
+- [GraphCMS](/examples/cms-graphcms)
+- [Kontent](/examples/cms-kontent)
+- [Umbraco Heartcore](/examples/cms-umbraco-heartcore)
+- [Builder.io](/examples/cms-builder-io)
+- [TinaCMS](/examples/cms-tina/)
+- [Enterspeed](/examples/cms-enterspeed)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example blog-starter blog-starter-app
+```
+
+```bash
+yarn create next-app --example blog-starter blog-starter-app
+```
+
+```bash
+pnpm create next-app --example blog-starter blog-starter-app
+```
+
+Your blog should be up and running on [http://localhost:3000](http://localhost:3000)! If it doesn't work, post on [GitHub discussions](https://github.com/vercel/next.js/discussions).
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+
+# Notes
+
+`blog-starter` uses [Tailwind CSS](https://tailwindcss.com) [(v3.0)](https://tailwindcss.com/blog/tailwindcss-v3).
diff --git a/examples/blog-starter/_posts/dynamic-routing.md b/examples/blog-starter/_posts/dynamic-routing.md
new file mode 100644
index 0000000000000..b6ef7a26e6ae0
--- /dev/null
+++ b/examples/blog-starter/_posts/dynamic-routing.md
@@ -0,0 +1,19 @@
+---
+title: 'Dynamic Routing and Static Generation'
+excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus.'
+coverImage: '/assets/blog/dynamic-routing/cover.jpg'
+date: '2020-03-16T05:35:07.322Z'
+author:
+ name: JJ Kasper
+ picture: '/assets/blog/authors/jj.jpeg'
+ogImage:
+ url: '/assets/blog/dynamic-routing/cover.jpg'
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
+
+Venenatis cras sed felis eget velit. Consectetur libero id faucibus nisl tincidunt. Gravida in fermentum et sollicitudin ac orci phasellus egestas tellus. Volutpat consequat mauris nunc congue nisi vitae. Id aliquet risus feugiat in ante metus dictum at tempor. Sed blandit libero volutpat sed cras. Sed odio morbi quis commodo odio aenean sed adipiscing. Velit euismod in pellentesque massa placerat. Mi bibendum neque egestas congue quisque egestas diam in arcu. Nisi lacus sed viverra tellus in. Nibh cras pulvinar mattis nunc sed. Luctus accumsan tortor posuere ac ut consequat semper viverra. Fringilla ut morbi tincidunt augue interdum velit euismod.
+
+## Lorem Ipsum
+
+Tristique senectus et netus et malesuada fames ac turpis. Ridiculous mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
diff --git a/examples/blog-starter/_posts/hello-world.md b/examples/blog-starter/_posts/hello-world.md
new file mode 100644
index 0000000000000..8d85a1df8f174
--- /dev/null
+++ b/examples/blog-starter/_posts/hello-world.md
@@ -0,0 +1,19 @@
+---
+title: 'Learn How to Pre-render Pages Using Static Generation with Next.js'
+excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus.'
+coverImage: '/assets/blog/hello-world/cover.jpg'
+date: '2020-03-16T05:35:07.322Z'
+author:
+ name: Tim Neutkens
+ picture: '/assets/blog/authors/tim.jpeg'
+ogImage:
+ url: '/assets/blog/hello-world/cover.jpg'
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
+
+Venenatis cras sed felis eget velit. Consectetur libero id faucibus nisl tincidunt. Gravida in fermentum et sollicitudin ac orci phasellus egestas tellus. Volutpat consequat mauris nunc congue nisi vitae. Id aliquet risus feugiat in ante metus dictum at tempor. Sed blandit libero volutpat sed cras. Sed odio morbi quis commodo odio aenean sed adipiscing. Velit euismod in pellentesque massa placerat. Mi bibendum neque egestas congue quisque egestas diam in arcu. Nisi lacus sed viverra tellus in. Nibh cras pulvinar mattis nunc sed. Luctus accumsan tortor posuere ac ut consequat semper viverra. Fringilla ut morbi tincidunt augue interdum velit euismod.
+
+## Lorem Ipsum
+
+Tristique senectus et netus et malesuada fames ac turpis. Ridiculous mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
diff --git a/examples/blog-starter/_posts/preview.md b/examples/blog-starter/_posts/preview.md
new file mode 100644
index 0000000000000..3d70ba7f99d11
--- /dev/null
+++ b/examples/blog-starter/_posts/preview.md
@@ -0,0 +1,19 @@
+---
+title: 'Preview Mode for Static Generation'
+excerpt: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus.'
+coverImage: '/assets/blog/preview/cover.jpg'
+date: '2020-03-16T05:35:07.322Z'
+author:
+ name: Joe Haddad
+ picture: '/assets/blog/authors/joe.jpeg'
+ogImage:
+ url: '/assets/blog/preview/cover.jpg'
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Praesent elementum facilisis leo vel fringilla est ullamcorper eget. At imperdiet dui accumsan sit amet nulla facilities morbi tempus. Praesent elementum facilisis leo vel fringilla. Congue mauris rhoncus aenean vel. Egestas sed tempus urna et pharetra pharetra massa massa ultricies.
+
+Venenatis cras sed felis eget velit. Consectetur libero id faucibus nisl tincidunt. Gravida in fermentum et sollicitudin ac orci phasellus egestas tellus. Volutpat consequat mauris nunc congue nisi vitae. Id aliquet risus feugiat in ante metus dictum at tempor. Sed blandit libero volutpat sed cras. Sed odio morbi quis commodo odio aenean sed adipiscing. Velit euismod in pellentesque massa placerat. Mi bibendum neque egestas congue quisque egestas diam in arcu. Nisi lacus sed viverra tellus in. Nibh cras pulvinar mattis nunc sed. Luctus accumsan tortor posuere ac ut consequat semper viverra. Fringilla ut morbi tincidunt augue interdum velit euismod.
+
+## Lorem Ipsum
+
+Tristique senectus et netus et malesuada fames ac turpis. Ridiculous mus mauris vitae ultricies leo integer malesuada nunc vel. In mollis nunc sed id semper. Egestas tellus rutrum tellus pellentesque. Phasellus vestibulum lorem sed risus ultricies tristique nulla. Quis blandit turpis cursus in hac habitasse platea dictumst quisque. Eros donec ac odio tempor orci dapibus ultrices. Aliquam sem et tortor consequat id porta nibh. Adipiscing elit duis tristique sollicitudin nibh sit amet commodo nulla. Diam vulputate ut pharetra sit amet. Ut tellus elementum sagittis vitae et leo. Arcu non odio euismod lacinia at quis risus sed vulputate.
diff --git a/examples/blog-starter/components/alert.tsx b/examples/blog-starter/components/alert.tsx
new file mode 100644
index 0000000000000..067672f380826
--- /dev/null
+++ b/examples/blog-starter/components/alert.tsx
@@ -0,0 +1,48 @@
+import Container from './container'
+import cn from 'classnames'
+import { EXAMPLE_PATH } from '../lib/constants'
+
+type Props = {
+ preview?: boolean
+}
+
+const Alert = ({ preview }: Props) => {
+ return (
+
+
+
+ {preview ? (
+ <>
+ This page is a preview.{' '}
+
+ Click here
+ {' '}
+ to exit preview mode.
+
+ ) : (
+ <>
+ The source code for this blog is{' '}
+
+ available on GitHub
+
+ .
+
+ )}
+
-
-[](https://www.npmjs.com/package/next)
-[](https://travis-ci.org/zeit/next.js)
-[](https://ci.appveyor.com/project/arunoda/next-js/branch/master)
-[](https://coveralls.io/r/zeit/next.js?branch=master)
-[](https://spectrum.chat/next-js)
-
-Next.js 是一个轻量级的 React 服务端渲染应用框架。
-
-**可访问 [nextjs.org/learn](https://nextjs.org/learn) 开始学习 Next.js.**
-
-[README in English](README.md)
-
----
-
-
-
-
-
-- [怎么使用](#how-to-use)
- - [安装](#setup)
- - [代码自动分割](#automatic-code-splitting)
- - [CSS](#css)
- - [支持嵌入样式](#built-in-css-support)
- - [内嵌样式](#css-in-js)
- - [使用 CSS / Sass / Less / Stylus files](#importing-css--sass--less--stylus-files)
- - [静态文件服务（如图像)](#static-file-serving-eg-images)
- - [``](#populating-head)
- - [获取数据以及组件生命周期](#fetching-data-and-component-lifecycle)
- - [路由](#routing)
- - [`` 用法](#with-link)
- - [URL 对象](#with-url-object)
- - [替换路由](#replace-instead-of-push-url)
- - [组件支持点击事件`onClick`](#using-a-component-that-supports-onclick)
- - [暴露`href`给子元素](#forcing-the-link-to-expose-href-to-its-child)
- - [禁止滚动到页面顶部](#disabling-the-scroll-changes-to-top-on-page)
- - [命令式](#imperatively)
- - [拦截器 `popstate`](#intercepting-popstate)
- - [URL 对象用法](#with-url-object-1)
- - [路由事件](#router-events)
- - [浅层路由](#shallow-routing)
- - [高阶组件](#using-a-higher-order-component)
- - [预加载页面](#prefetching-pages)
- - [``用法](#with-link-1)
- - [命令式 prefetch 写法](#imperatively-1)
- - [自定义服务端路由](#custom-server-and-routing)
- - [禁止文件路由](#disabling-file-system-routing)
- - [动态前缀](#dynamic-assetprefix)
- - [动态导入](#dynamic-import)
- - [1. 基础支持 (同样支持 SSR)](#1-basic-usage-also-does-ssr)
- - [2. 自定义加载组件](#2-with-custom-loading-component)
- - [3. 禁止使用 SSR](#3-with-no-ssr)
- - [4. 同时加载多个模块](#4-with-multiple-modules-at-once)
- - [自定义 `
;
-```
-
-_注意：不要自定义静态文件夹的名字，只能叫`static` ，因为只有这个名字 Next.js 才会把它当作静态资源。_
-
-
-
- 
- 