vercel · Aug 5, 2022 · Aug 5, 2022 · Aug 5, 2022 · Aug 5, 2022 · Aug 5, 2022
Showing 364 changed files with 4,885 additions and 3,074 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -69,9 +69,10 @@
           "warn",
           {
             "functions": false,
-            "classes": false,
-            "variables": false,
-            "typedefs": false
+            "classes": true,
+            "variables": true,
+            "enums": true,
+            "typedefs": true
           }
         ],
         "no-unused-vars": "off",
@@ -106,6 +107,16 @@
     {
       "files": ["examples/**/*"],
       "rules": {
+        "@typescript-eslint/no-use-before-define": [
+          "error",
+          {
+            "functions": true,
+            "classes": true,
+            "variables": true,
+            "enums": true,
+            "typedefs": true
+          }
+        ],
         "import/no-anonymous-default-export": [
           "error",
           {
@@ -145,6 +156,30 @@
           }
         ]
       }
+    },
+    {
+      "files": [
+        "packages/eslint-plugin-next/**/*.js",
+        "test/unit/eslint-plugin-next/**/*.test.ts"
+      ],
+      "extends": ["plugin:eslint-plugin/recommended"],
+      "parserOptions": {
+        "sourceType": "script"
+      },
+      "rules": {
+        "eslint-plugin/prefer-replace-text": "error",
+        "eslint-plugin/report-message-format": [
+          "error",
+          ".+\\. See: https://nextjs.org/docs/messages/[a-z\\-]+$"
+        ],
+        "eslint-plugin/require-meta-docs-description": [
+          "error",
+          {
+            "pattern": ".+"
+          }
+        ],
+        "eslint-plugin/require-meta-docs-url": "error"
+      }
     }
   ],
   "rules": {

diff --git a/.github/workflows/build_test_deploy.yml b/.github/workflows/build_test_deploy.yml
@@ -1463,7 +1463,7 @@ jobs:
           rm -rf test
       - name: Build
         id: build
-        uses: vmactions/freebsd-vm@v0.2.0
+        uses: vmactions/freebsd-vm@v0.2.3
         env:
           DEBUG: napi:*
           RUSTUP_HOME: /usr/local/rustup
@@ -1493,8 +1493,8 @@ jobs:
             whoami
             env
             freebsd-version
-            npm i -g "@napi-rs/cli@${NAPI_CLI_VERSION}" "turbo@${TURBO_VERSION}" && if [ ! -f $(dirname $(which yarn))/pnpm ]; then ln -s $(which yarn) $(dirname $(which yarn))/pnpm;fi
-            yarn --cwd=packages/next-swc build-native-no-plugin --release --target x86_64-unknown-freebsd
+            npm i -g "@napi-rs/cli@${NAPI_CLI_VERSION}"
+            cd packages/next-swc && napi build --platform -p next-swc-napi --cargo-name next_swc_napi native --release --target x86_64-unknown-freebsd
             rm -rf node_modules
             rm -rf packages/next-swc/target
       - name: Upload artifact

diff --git a/contributing.md b/contributing.md
@@ -30,9 +30,9 @@ To develop locally:
    ```
    git checkout -b MY_BRANCH_NAME
    ```
-3. Install pnpm:
+3. Enable pnpm:
    ```
-   npm install -g pnpm
+   corepack enable pnpm
    ```
 4. Install the dependencies with:
    ```

diff --git a/docs/advanced-features/compiler.md b/docs/advanced-features/compiler.md
@@ -358,7 +358,7 @@ This transform uses [handlebars](https://docs.rs/handlebars) to template the rep
 
 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`: Helper functions to convert a string to lower, upper or camel cases.
+3. `lowerCase`, `upperCase`, `camelCase`, `kebabCase`: Helper functions to convert a string to lower, upper, camel or kebab cases.
 
 ### SWC Trace profiling
 

diff --git a/docs/advanced-features/preview-mode.md b/docs/advanced-features/preview-mode.md
@@ -194,10 +194,12 @@ Then, send a request to `/api/clear-preview-mode-cookies` to invoke the API Rout
 `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
 })
 ```
 

diff --git a/docs/api-reference/data-fetching/get-server-side-props.md b/docs/api-reference/data-fetching/get-server-side-props.md
@@ -33,7 +33,7 @@ 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.
+- `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.

diff --git a/docs/api-reference/next/future/image.md b/docs/api-reference/next/future/image.md
@@ -43,19 +43,9 @@ Compared to `next/image`, the new `next/future/image` component has the followin
 
 ## Migration
 
-Although `layout` is not available, you can migrate `next/image` to `next/future/image` using a few props. The following is a comparison of the two components:
+Although `layout` is not available, you can migrate `next/image` to `next/future/image` using a few props. The following code snippets compare the two components:
 
-<table>
-<thead>
-  <tr>
-    <th>next/image</th>
-    <th>next/future/image</th>
-  </tr>
-</thead>
-<tbody>
-
-<tr>
-<td>
+#### before: `next/image`
 
 ```jsx
 import Image from 'next/image'
@@ -66,8 +56,7 @@ function Page() {
 }
 ```
 
-</td>
-<td>
+#### after: `next/future/image`
 
 ```jsx
 import Image from 'next/future/image'
@@ -79,11 +68,7 @@ function Page() {
 }
 ```
 
-</td>
-</tr>
-
-<tr>
-<td>
+#### before: `next/image`
 
 ```jsx
 import Image from 'next/image'
@@ -94,8 +79,7 @@ function Page() {
 }
 ```
 
-</td>
-<td>
+#### after: `next/future/image`
 
 ```jsx
 import Image from 'next/future/image'
@@ -107,11 +91,7 @@ function Page() {
 }
 ```
 
-</td>
-</tr>
-
-<tr>
-<td>
+#### before: `next/image`
 
 ```jsx
 import Image from 'next/image'
@@ -122,8 +102,7 @@ function Page() {
 }
 ```
 
-</td>
-<td>
+#### after: `next/future/image`
 
 ```jsx
 import Image from 'next/future/image'
@@ -134,11 +113,7 @@ function Page() {
 }
 ```
 
-</td>
-</tr>
-
-<tr>
-<td>
+#### before: `next/image`
 
 ```jsx
 import Image from 'next/image'
@@ -149,8 +124,7 @@ function Page() {
 }
 ```
 
-</td>
-<td>
+#### after: `next/future/image`
 
 ```jsx
 import Image from 'next/future/image'
@@ -161,12 +135,6 @@ function Page() {
 }
 ```
 
-</td>
-</tr>
-
-</tbody>
-</table>
-
 You can also use `className` instead of `style`.
 
 ## Required Props
@@ -251,11 +219,37 @@ See also:
 
 ### sizes
 
-A string that provides information about how wide the image will be at different breakpoints.
+A string that provides information about how wide the image will be at different breakpoints. The value of `sizes` will greatly affect performance for images using [`fill`](#fill) or which are styled to have a responsive size.
+
+The `sizes` property serves two important purposes related to image performance:
+
+First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/future/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is the same size or larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value in an image with the `fill` property, a default value of `100vw` (full screen width) is used.
+
+Second, the `sizes` property configures how `next/future/image` automatically generates an image source set. If no `sizes` value is present, a small source set is generated, suitable for a fixed-size image. If `sizes` is defined, a large source set is generated, suitable for a responsive image. If the `sizes` property includes sizes such as `50vw`, which represent a percentage of the viewport width, then the source set is trimmed to not include any values which are too small to ever be necessary.
+
+For example, if you know your styling will cause an image to be full-width on mobile devices, in a 2-column layout on tablets, and a 3-column layout on desktop displays, you should include a sizes property such as the following:
+
+```js
+import Image from 'next/image'
+const Example = () => (
+  <div className="grid-element">
+    <Image
+      src="/example.png"
+      layout="fill"
+      sizes="(min-width: 75em) 33vw,
+              (min-width: 48em) 50vw,
+              100vw"
+    />
+  </div>
+)
+```
+
+This example `sizes` could have a dramatic effect on performance metrics. Without the `33vw` sizes, the image selected from the server would be 3 times as wide as it needs to be. Because file size is proportional to the square of the width, without `sizes` the user would download an image that's 9 times larger than necessary.
 
-It's important to assign `sizes` for responsive images that takes up less than the full viewport width. For example, when the parent element will constrain the image to always be less than half the viewport width, use `sizes="50vw"`. Without `sizes`, the image will be sent at twice the necessary resolution, decreasing performance.
+Learn more about `srcset` and `sizes`:
 
-[Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes).
+- [web.dev](https://web.dev/learn/design/responsive-images/#sizes)
+- [mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes)
 
 ### quality
 

diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md
@@ -131,15 +131,37 @@ const MyImage = (props) => {
 
 ### sizes
 
-A string that provides information about how wide the image will be at different breakpoints. Defaults to `100vw` (the full width of the screen) when using `layout="responsive"` or `layout="fill"`.
+A string that provides information about how wide the image will be at different breakpoints. The value of `sizes` will greatly affect performance for images using `layout="responsive"` or `layout="fill"`. It will be ignored for images using `layout="intrinsic"` or `layout="fixed"`.
 
-If you are using `layout="fill"` or `layout="responsive"` it's important to assign `sizes` for any image that takes up less than the full viewport width.
+The `sizes` property serves two important purposes related to image performance:
 
-For example, when the parent element will constrain the image to always be less than half the viewport width, use `sizes="50vw"`. Without `sizes`, the image will be sent at twice the necessary resolution, decreasing performance.
+First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is the same size or larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value, a default value of `100vw` (full screen width) is used.
 
-If you are using `layout="intrinsic"` or `layout="fixed"`, then `sizes` is not needed because the upper bound width is constrained already.
+Second, the `sizes` value is parsed and used to trim the values in the automatically-created source set. If the `sizes` property includes sizes such as `50vw`, which represent a percentage of the viewport width, then the source set is trimmed to not include any values which are too small to ever be necessary.
 
-[Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes).
+For example, if you know your styling will cause an image to be full-width on mobile devices, in a 2-column layout on tablets, and a 3-column layout on desktop displays, you should include a sizes property such as the following:
+
+```js
+import Image from 'next/image'
+const Example = () => (
+  <div className="grid-element">
+    <Image
+      src="/example.png"
+      layout="fill"
+      sizes="(min-width: 75em) 33vw,
+              (min-width: 48em) 50vw,
+              100vw"
+    />
+  </div>
+)
+```
+
+This example `sizes` could have a dramatic effect on performance metrics. Without the `33vw` sizes, the image selected from the server would be 3 times as wide as it needs to be. Because file size is proportional to the square of the width, without `sizes` the user would download an image that's 9 times larger than necessary.
+
+Learn more about `srcset` and `sizes`:
+
+- [web.dev](https://web.dev/learn/design/responsive-images/#sizes)
+- [mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes)
 
 ### quality
 

diff --git a/docs/api-reference/next/router.md b/docs/api-reference/next/router.md
@@ -248,14 +248,16 @@ export default function Page() {
 
 Prefetch pages for faster client-side transitions. This method is only useful for navigations without [`next/link`](/docs/api-reference/next/link.md), as `next/link` takes care of prefetching pages automatically.
 
-> This is a production only feature. Next.js doesn't prefetch pages on development.
+> This is a production only feature. Next.js doesn't prefetch pages in development.
 
 ```jsx
-router.prefetch(url, as)
+router.prefetch(url, as, options)
 ```
 
 - `url` - The URL to prefetch, including explicit routes (e.g. `/dashboard`) and dynamic routes (e.g. `/product/[id]`)
 - `as` - Optional decorator for `url`. Before Next.js 9.5.3 this was used to prefetch dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked
+- `options` - Optional object with the following allowed fields:
+  - `locale` - allows providing a different locale from the active one. If `false`, `url` has to include the locale as the active locale won't be used.
 
 #### Usage
 

diff --git a/docs/api-routes/introduction.md b/docs/api-routes/introduction.md
@@ -8,7 +8,6 @@ description: Next.js supports API Routes, which allow you to build your API with
   <summary><b>Examples</b></summary>
   <ul>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes">Basic API Routes</a></li>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-middleware">API Routes with middleware</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-graphql">API Routes with GraphQL</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-rest">API Routes with REST</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-cors">API Routes with CORS</a></li>
@@ -31,7 +30,7 @@ export default function handler(req, res) {
 
 For an API route to work, you need to export a function as default (a.k.a **request handler**), which then receives the following parameters:
 
-- `req`: An instance of [http.IncomingMessage](https://nodejs.org/api/http.html#class-httpincomingmessage), plus some [pre-built middlewares](/docs/api-routes/api-middlewares.md)
+- `req`: An instance of [http.IncomingMessage](https://nodejs.org/api/http.html#class-httpincomingmessage), plus some [pre-built middlewares](/docs/api-routes/request-helpers.md)
 - `res`: An instance of [http.ServerResponse](https://nodejs.org/api/http.html#class-httpserverresponse), plus some [helper functions](/docs/api-routes/response-helpers.md)
 
 To handle different HTTP methods in an API route, you can use `req.method` in your request handler, like so:
@@ -57,17 +56,17 @@ 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 request helpers](https://github.com/vercel/next.js/tree/canary/examples/api-routes-cors).
 - API Routes can't be used with [`next export`](/docs/advanced-features/static-html-export.md)
 
 ## Related
 
 For more information on what to do next, we recommend the following sections:
 
 <div class="card">
-  <a href="/docs/api-routes/api-middlewares.md">
-    <b>API Middlewares:</b>
-    <small>learn about the built-in middlewares for the request.</small>
+  <a href="/docs/api-routes/request-helpers.md">
+    <b>API Routes Request Helpers:</b>
+    <small>learn about the built-in helpers for the request.</small>
   </a>
 </div>