Merge branch 'canary' into x-modern-legacy-doc-2

.eslintignore

@@ -8,6 +8,7 @@ examples/with-typescript-eslint-jest/**
 examples/with-kea/**
 examples/with-custom-babel-config/**
 examples/with-flow/**
+examples/with-jest/**
 examples/with-mobx-state-tree/**
 examples/with-mobx/**
 packages/next/bundles/webpack/packages/*.runtime.js

.github/workflows/build_test_deploy.yml

@@ -104,7 +104,7 @@ jobs:
           path: ./*
           key: ${{ github.sha }}
 
-      - run: node run-tests.js --timings --type unit -g 1/1
+      - run: node run-tests.js --type unit
         if: ${{needs.build.outputs.docsChange != 'docs only change'}}
 
   testIntegration:

azure-pipelines.yml

@@ -111,7 +111,7 @@ stages:
               path: $(System.DefaultWorkingDirectory)
             displayName: Cache Build
           - script: |
-              node run-tests.js -g 1/1 --timings --azure --type unit
+              node run-tests.js --type unit
             displayName: 'Run tests'
       # TODO: investigate re-enabling when stability matches running in
       # tests in ubuntu environment

docs/advanced-features/i18n-routing.md

@@ -234,6 +234,30 @@ Next.js doesn't know about variants of a page so it's up to you to add the `href
 
 > 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.md#getstaticpaths-static-generation). 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](https://nextjs.org/docs/basic-features/data-fetching#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.
@@ -265,24 +289,9 @@ export async function getStaticProps({ locale }) {
 }
 ```
 
-### Dynamic getStaticProps Pages
-
-For dynamic `getStaticProps` pages, any locale variants of the page that is desired to be prerendered needs to be returned from [`getStaticPaths`](/docs/basic-features/data-fetching.md#getstaticpaths-static-generation). Along with the `params` object that can be returned for the `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: [
-      { params: { slug: 'post-1' }, locale: 'en-US' },
-      { params: { slug: 'post-1' }, locale: 'fr' },
-    ],
-    fallback: true,
-  }
-}
-```
-
 ## 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). We are continuing to evaluate if these limits are sufficient.

docs/api-routes/introduction.md

@@ -55,7 +55,7 @@ For new projects, you can build your entire API with API Routes. If you have an
 
 ## Caveats
 
-- API Routes [do not specify CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), meaning they are **same-origin only** by default. You can customize such behavior by wrapping the request handler with the [cors middleware](/docs/api-routes/api-middlewares.md#connectexpress-middleware-support).
+- API Routes [do not specify CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), meaning they are **same-origin only** by default. You can customize such behavior by wrapping the request handler with the [CORS middleware](/docs/api-routes/api-middlewares.md#connectexpress-middleware-support).
 - API Routes can't be used with [`next export`](/docs/advanced-features/static-html-export.md)
 
 ## Related

docs/basic-features/image-optimization.md

@@ -128,7 +128,7 @@ If you need a different provider, you can use the [`loader`](/docs/api-reference
 
 > 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.
 
-> The `next/image` component's default loader uses the ['squoosh'](https://www.npmjs.com/package/@squoosh/lib) library for image resizing and optimization. This library is quick to install and suitable for a dev server environment. For a production environment, it is strongly recommended that you install the optional [`sharp`](https://www.npmjs.com/package/sharp) library by running `yarn add sharp` in your project directory. If sharp is already installed but can't be resolved you can manually pass the path to it via the `NEXT_SHARP_PATH` environment variable e.g. `NEXT_SHARP_PATH=/tmp/node_modules/sharp`
+> 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. When using `next start` in your production environment, it is strongly recommended that you install [`sharp`](https://www.npmjs.com/package/sharp) by running `yarn add sharp` in your project directory. This is not necessary for Vercel deployments, as `sharp` is installed automatically.
 
 ## Caching
 

docs/testing.md

@@ -179,6 +179,7 @@ module.exports = {
     '^.+\\.(jpg|jpeg|png|gif|webp|svg)$': '<rootDir>/__mocks__/fileMock.js',
   },
   testPathIgnorePatterns: ['<rootDir>/node_modules/', '<rootDir>/.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
@@ -276,16 +277,16 @@ Your project is now ready to run tests. Follow Jests convention by adding tests
 For example, we can add a test to check if the `<Index />` component successfully renders a heading:
 
 ```jsx
-// __tests__/testing-library.js
+// __tests__/index.test.jsx
 import React from 'react'
-import { render } from '@testing-library/react'
-import Index from '../pages/index'
+import { render, screen } from '@testing-library/react'
+import Home from '../pages/index'
 
-describe('App', () => {
+describe('Home', () => {
   it('renders a heading', () => {
-    const { getByRole } = render(<Index />)
+    render(<Home />)
 
-    const heading = getByRole('heading', {
+    const heading = screen.getByRole('heading', {
       name: /welcome to next\.js!/i,
     })
 

errors/invalid-api-status-body.md

@@ -0,0 +1,32 @@
+Invalid API Route Status/Body Response
+
+#### Why This Error Occurred
+
+In one of your API routes a 204 or 304 status code was used as well as sending a response body.
+
+This is invalid as a 204 or 304 status code dictates no response body should be present.
+
+#### Possible Ways to Fix It
+
+Send an empty body when using a 204 or 304 status code or use a different status code while sending a response body.
+
+Before
+
+```js
+export default function handler(req, res) {
+  res.status(204).send('invalid body')
+}
+```
+
+After
+
+```js
+export default function handler(req, res) {
+  res.status(204).send()
+}
+```
+
+### Useful Links
+
+- [204 status code documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204)
+- [304 status code documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304)

errors/manifest.json

@@ -454,6 +454,10 @@
         {
           "title": "next-config-error",
           "path": "/errors/next-config-error.md"
+        },
+        {
+          "title": "invalid-api-status-body",
+          "path": "/errors/invalid-api-status-body.md"
         }
       ]
     }

errors/sharp-missing-in-production.md

@@ -2,11 +2,16 @@
 
 #### Why This Error Occurred
 
-The `next/image` component's default loader uses the ['squoosh'](https://www.npmjs.com/package/@squoosh/lib) library for image resizing and optimization. This library is quick to install and suitable for a dev server environment. For a production environment, it is strongly recommended that you install the optional [`sharp`](https://www.npmjs.com/package/sharp). This package was not detected when leveraging the Image Optimization in production mode (`next start`).
+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) by running `yarn add sharp` in your project directory.
+
+You are seeing this error because Image Optimization in production mode (`next start`) was detected.
 
 #### Possible Ways to Fix It
 
-Install `sharp` by running `yarn add sharp` in your project directory.
+- Install `sharp` by running `yarn add sharp` in your project directory and then reboot the server by running `next start` again
+- If `sharp` is already installed but can't be resolved, set the `NEXT_SHARP_PATH` environment variable such as `NEXT_SHARP_PATH=/tmp/node_modules/sharp next start`
+
+> Note: This is not necessary for Vercel deployments, since `sharp` is installed automatically for you.
 
 ### Useful Links
 

examples/active-class-name/package.json

@@ -8,6 +8,7 @@
   "dependencies": {
     "next": "latest",
     "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react-dom": "^17.0.2",
+    "prop-types": "^15.7.2"
   }
 }

examples/with-couchbase/.env.local.example

@@ -0,0 +1,5 @@
+COUCHBASE_USER=
+COUCHBASE_PASSWORD=
+COUCHBASE_ENDPOINT=
+COUCHBASE_BUCKET=
+IS_CLOUD_INSTANCE=

examples/with-couchbase/.gitignore

@@ -0,0 +1,33 @@
+# 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
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE Files
+.idea/

examples/with-couchbase/README.md

@@ -0,0 +1,95 @@
+## Example app using Couchbase
+
+[Couchbase](https://www.couchbase.com/) is a modern database for enterprise applications. This example will show you how to connect to and use Couchbase in your Next.js app.
+
+If you want to learn more about Couchbase, visit the following pages:
+
+- [Couchbase Docs](https://docs.couchbase.com/)
+- [Couchbase Developer Portal](https://developer.couchbase.com/)
+- [Couchbase Cloud](https://cloud.couchbase.com/sign-up)
+
+## Preview
+
+Preview the example live on [StackBlitz](http://stackblitz.com/):
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/with-couchbase)
+
+## Deploy your own
+
+Once you have access to the environment variables you'll need, deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/with-couchbase&project-name=with-couchbase&repository-name=with-couchbase&env=COUCHBASE_USER,COUCHBASE_PASSWORD,COUCHBASE_ENDPOINT,COUCHBASE_BUCKET,IS_CLOUD_INSTANCE&envDescription=Required%20to%20connect%20the%20app%20with%20Couchbase)
+
+## 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) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example:
+
+```bash
+npx create-next-app --example with-couchbase with-couchbase-app
+# or
+yarn create next-app --example with-couchbase with-couchbase-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
+
+### Set up a Couchbase database
+
+Set up a Couchbase database either locally or with [Couchbase Cloud](https://cloud.couchbase.com/sign-up).
+
+Local installation can be accomplished through a variety of methods, but [Docker](https://docs.couchbase.com/server/current/install/getting-started-docker.html) is the simplest.
+
+After Couchbase is installed, set up a cluster by following [this tutorial](https://docs.couchbase.com/server/current/manage/manage-nodes/create-cluster.html).
+
+- _NOTE:_ the **eventing** and **analytics** services can be unchecked if memory is a constraint (this is often the case with docker and other local installations).
+
+A variety of sample buckets can be installed to get up and running with a data model quickly.
+
+### Set up environment variables
+
+Copy the `env.local.example` file in this directory to `.env.local` (which will be ignored by Git):
+
+```bash
+cp .env.local.example .env.local
+```
+
+Set each variable on `.env.local`:
+
+- `COUCHBASE_USERNAME` - The username of an authorized user on your Couchbase instance
+- `COUCHBASE_PASSWORD` - The corresponding password for the username specified above
+- `COUCHBASE_ENDPOINT` - The endpoint to connect to. Use `localhost` for a local instance of Couchbase, or the Wide Area Network address for a cloud instance.
+- `COUCHBASE_BUCKET` - The bucket you'd like to connect to for testing.
+- `IS_CLOUD_INSTANCE` - `true` if you are trying to connect to an instance of Couchbase Cloud, `false` otherwise.
+
+### Run Next.js in development mode
+
+```bash
+npm install
+npm run dev
+# or
+yarn install
+yarn dev
+```
+
+Your app 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).
+
+You will either see a message stating "You are connected to Couchbase" or "You are NOT connected to Couchbase". Ensure that you have provided the correct environment variables.
+
+When you are successfully connected, you can refer to the [Couchbase Node.js SDK docs](https://docs.couchbase.com/nodejs-sdk/current/hello-world/start-using-sdk.html) for further instructions on how to query your database.
+
+## Deploy on Vercel
+
+You can deploy this app to the cloud with [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
+
+#### Deploy Your Local Project
+
+To deploy your local project to Vercel, push it to GitHub/GitLab/Bitbucket and [import to Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example).
+
+## Notes
+
+- When you import your project on Vercel, make sure to click on **Environment Variables** and set the keys to match your `.env.local` file.
+
+- For a cloud deployment on Vercel, the **Environment Variables** values will need to **correspond to a cloud instance of Couchbase** (localhost will **NOT** connect from a remote server such as Vercel). Find info on [getting started with Couchbase cloud](https://developer.couchbase.com/tutorial-cloud-getting-started/).
+
+  - _Important:_ you will have to allowlist 0.0.0.0/0 as the IP address, since Vercel's serverless deployments use [dynamic IP addresses](https://vercel.com/docs/solutions/databases#allowing-&-blocking-ip-addresses)

examples/with-couchbase/package.json

@@ -0,0 +1,14 @@
+{
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "couchbase": "^3.1.3",
+    "next": "latest",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2"
+  }
+}

examples/with-couchbase/pages/_app.js

@@ -0,0 +1,7 @@
+import '../styles/globals.css'
+
+function MyApp({ Component, pageProps }) {
+  return <Component {...pageProps} />
+}
+
+export default MyApp