Merge branch 'canary' into fix-excessive-experiment-warning

.github/ISSUE_TEMPLATE/1.bug_report.yml

@@ -7,49 +7,28 @@ body:
       value: Thanks for taking the time to file a bug report! Please fill out this form as completely as possible.
   - type: markdown
     attributes:
-      value: If you leave out sections there is a high likelihood it will be moved to the GitHub Discussions "Help" section.
-  - type: markdown
-    attributes:
-      value: 'Please first verify if your issue exists in the Next.js canary release line: `npm install next@canary`.'
-  - type: markdown
-    attributes:
-      value: 'next@canary is the beta version of Next.js. It includes all features and fixes that are pending to land on the stable release line.'
+      value: If you leave out sections there is a high likelihood it will be moved to the GitHub Discussions ["Help" section](https://github.com/vercel/next.js/discussions/categories/help).
+  - type: checkboxes
+    attributes:
+      label: Verify canary release
+      description: '`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.'
+      options:
+        - label: I verified that the issue exists in Next.js canary release
+          required: true
   - type: textarea
     attributes:
-      label: Run `next info` (available from version 12.0.8 and up)
+      label: Provide environment information
       description: Please run `next info` in the root directory of your project and paste the results. You might need to use `npx --no-install next info` if next is not in the current PATH.
-    validations:
-      required: false
-  - type: input
-    attributes:
-      label: What version of Next.js are you using?
-      description: 'For example: 10.0.1'
     validations:
       required: true
   - type: input
     attributes:
-      label: What version of Node.js are you using?
-      description: 'For example: 12.0.0'
-    validations:
-      required: true
+      label: What browser are you using? (if relevant)
+      description: 'Please specify the exact version. For example: Chrome 100.0.4878.0'
   - type: input
     attributes:
-      label: What browser are you using?
-      description: 'For example: Chrome, Safari'
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: What operating system are you using?
-      description: 'For example: macOS, Windows'
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: How are you deploying your application?
+      label: How are you deploying your application? (if relevant)
       description: 'For example: next start, next export, Vercel, Other platform'
-    validations:
-      required: true
   - type: textarea
     attributes:
       label: Describe the Bug

.github/ISSUE_TEMPLATE/2.example_bug_report.yml

@@ -1,49 +1,40 @@
 name: Example Bug Report
-description: Create a bug report for the examples
+description: Create a bug report for one of the Next.js examples
 labels: 'type: example,template: bug'
 body:
   - type: markdown
     attributes:
-      value: Thanks for taking the time to file a examples bug report! Please fill out this form as completely as possible.
+      value: Thanks for taking the time to file a bug report for [one of the examples](https://github.com/vercel/next.js/tree/canary/examples)! Please fill out this form as completely as possible.
   - type: markdown
     attributes:
-      value: If you leave out sections there is a high likelihood it will be moved to the GitHub Discussions "Help" section.
-  - type: input
+      value: If you leave out sections there is a high likelihood it will be moved to the GitHub Discussions ["Help" section](https://github.com/vercel/next.js/discussions/categories/help).
+  - type: checkboxes
     attributes:
-      label: What example does this report relate to?
-      description: 'For example: with-styled-components'
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: What version of Next.js are you using?
-      description: 'For example: 10.0.1'
-    validations:
-      required: true
-  - type: input
+      label: Verify canary release
+      description: '`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.'
+      options:
+        - label: I verified that the issue exists in Next.js canary release
+          required: true
+  - type: textarea
     attributes:
-      label: What version of Node.js are you using?
-      description: 'For example: 12.0.0'
+      label: Provide environment information
+      description: Please run `next info` in the root directory of your project and paste the results. You might need to use `npx --no-install next info` if next is not in the current PATH.
     validations:
       required: true
   - type: input
     attributes:
-      label: What browser are you using?
-      description: 'For example: Chrome, Safari'
+      label: Which example does this report relate to?
+      description: "See a complete list in the [examples folder](https://github.com/vercel/next.js/tree/canary/examples). For example: with-styled-components. Note: Examples not in the examples folder might be maintained by the example's library author. Check out their projects before opening the issue on Next.js"
     validations:
       required: true
   - type: input
     attributes:
-      label: What operating system are you using?
-      description: 'For example: macOS, Windows'
-    validations:
-      required: true
+      label: What browser are you using? (if relevant)
+      description: 'Please specify the exact version. For example: Chrome 100.0.4878.0'
   - type: input
     attributes:
-      label: How are you deploying your application?
+      label: How are you deploying your application? (if relevant)
       description: 'For example: next start, next export, Vercel, Other platform'
-    validations:
-      required: true
   - type: textarea
     attributes:
       label: Describe the Bug

docs/advanced-features/react-18/overview.md

@@ -19,10 +19,10 @@ You can now start using React 18's new APIs like `startTransition` and `Suspense
 
 Streaming server-rendering (SSR) is an experimental feature in Next.js 12. When enabled, SSR will use the same [Edge Runtime](/docs/api-reference/edge-runtime.md) as [Middleware](/docs/middleware.md).
 
-[Learn how to enable streaming in Next.js.](/docs/react-18/streaming.md)
+[Learn how to enable streaming in Next.js.](/docs/advanced-features/react-18/streaming.md)
 
 ## React Server Components (Alpha)
 
 Server Components are a new feature in React that let you reduce your JavaScript bundle size by separating server and client-side code. Server Components allow developers to build apps that span the server and client, combining the rich interactivity of client-side apps with the improved performance of traditional server rendering.
 
-Server Components are still in research and development. [Learn how to try Server Components](/docs/react-18/server-components.md) as an experimental feature in Next.js.
+Server Components are still in research and development. [Learn how to try Server Components](/docs/advanced-features/react-18/server-components.md) as an experimental feature in Next.js.

docs/advanced-features/react-18/server-components.md

@@ -59,7 +59,7 @@ The `<Home>` and `<Profile>` components will always be server-side rendered and
 
 > Make sure you're using default imports and exports for server components (`.server.js`). The support of named exports are a work in progress!
 
-To see a full example, check out the [hello world example](https://github.com/vercel/next.js/tree/canary/examples/react-server-components) or the larger [vercel/next-rsc-demo demo](https://github.com/vercel/next-rsc-demo).
+To see a full example, check out the [vercel/next-react-server-components demo](https://github.com/vercel/next-react-server-components).
 
 ## Supported Next.js APIs
 

docs/advanced-features/using-mdx.md

@@ -51,7 +51,8 @@ The following steps outline how to setup `@next/mdx` in your Next.js project:
      },
    })
    module.exports = withMDX({
-     pageExtensions: ['js', 'jsx', 'md', 'mdx'],
+     // Append the default value with md extensions
+     pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
    })
    ```
 

docs/api-reference/data-fetching/get-static-paths.md

@@ -7,10 +7,12 @@ description: API reference for `getStaticPaths`. Learn how to fetch data and gen
 <details>
   <summary><b>Version History</b></summary>
 
-| Version  | Changes                                                                                                         |
-| -------- | --------------------------------------------------------------------------------------------------------------- |
+| Version | Changes |
+| ------- | ------- |
+
+| `v12.1.0` | [On-demand Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md#on-demand-revalidation-beta) added (Beta). |
 | `v9.5.0` | Stable [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md) |
-| `v9.3.0` | `getStaticPaths` introduced.                                                                                    |
+| `v9.3.0` | `getStaticPaths` introduced. |
 
 </details>
 

docs/api-reference/data-fetching/get-static-props.md

@@ -7,12 +7,14 @@ description: API reference for `getStaticProps`. Learn how to use `getStaticProp
 <details>
   <summary><b>Version History</b></summary>
 
-| Version   | Changes                                                                                                           |
-| --------- | ----------------------------------------------------------------------------------------------------------------- |
-| `v10.0.0` | `locale`, `locales`, `defaultLocale`, and `notFound` options added.                                               |
-| `v9.5.0`  | Stable [Incremental Static Regeneration](https://nextjs.org/blog/next-9-5#stable-incremental-static-regeneration) |
-| `v9.3.0`  | `getStaticProps` introduced.                                                                                      |
-| `v10.0.0` | `fallback: 'blocking'` return option added.                                                                       |
+| Version | Changes |
+| ------- | ------- |
+
+| `v12.1.0` | [On-demand Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md#on-demand-revalidation-beta) 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>
 

docs/api-reference/next/image.md

@@ -16,7 +16,8 @@ description: Enable Image Optimization with the built-in Image component.
 
 | Version   | Changes                                                                                           |
 | --------- | ------------------------------------------------------------------------------------------------- |
-| `v12.0.9` | `lazyRoot` prop added                                                                             |
+| `v12.1.0` | `dangerouslyAllowSVG` and `contentSecurityPolicy` configuration added.                            |
+| `v12.0.9` | `lazyRoot` prop added.                                                                            |
 | `v12.0.0` | `formats` configuration added.<br/>AVIF support added.<br/>Wrapper `<div>` changed to `<span>`.   |
 | `v11.1.0` | `onLoadingComplete` and `lazyBoundary` props added.                                               |
 | `v11.0.0` | `src` prop support for static import.<br/>`placeholder` prop added.<br/>`blurDataURL` prop added. |
@@ -401,7 +402,7 @@ module.exports = {
 
 The following describes the caching algorithm for the default [loader](#loader). For all other loaders, please refer to your cloud provider's documentation.
 
-Images are optimized dynamically upon request and stored in the `<distDir>/cache/images` directory. The optimized image file will be served for subsequent requests until the expiration is reached. When a request is made that matches a cached but expired file, the cached file is deleted before generating a new optimized image and caching the new file.
+Images are optimized dynamically upon request and stored in the `<distDir>/cache/images` directory. The optimized image file will be served for subsequent requests until the expiration is reached. When a request is made that matches a cached but expired file, the expired image is served stale immediately. Then the image is optimized again in the background (also called revalidation) and saved to the cache with the new expiration date.
 
 The expiration (or rather Max Age) is defined by either the [`minimumCacheTTL`](#minimum-cache-ttl) configuration or the upstream server's `Cache-Control` header, whichever is larger. Specifically, the `max-age` value of the `Cache-Control` header is used. If both `s-maxage` and `max-age` are found, then `s-maxage` is preferred.
 
@@ -439,6 +440,21 @@ module.exports = {
 }
 ```
 
+### Dangerously Allow SVG
+
+The default [loader](#loader) does not optimize SVG images for a few reasons. First, SVG is a vector format meaning it can be resized losslessly. Second, SVG has many of the same features as HTML/CSS, which can lead to vulnerabilities without proper [Content Security Policy (CSP) headers](/docs/advanced-features/security-headers.md).
+
+If you need to serve SVG images with the default Image Optimization API, you can set `dangerouslyAllowSVG` and `contentSecurityPolicy` inside your `next.config.js`:
+
+```js
+module.exports = {
+  images: {
+    dangerouslyAllowSVG: true,
+    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
+  },
+}
+```
+
 ## Related
 
 For an overview of the Image component features and usage guidelines, see:

docs/api-routes/response-helpers.md

@@ -12,6 +12,7 @@ The included helpers are:
 - `res.json(body)` - Sends a JSON response. `body` must be a [serializable object](https://developer.mozilla.org/en-US/docs/Glossary/Serialization)
 - `res.send(body)` - Sends the HTTP response. `body` can be a `string`, an `object` or a `Buffer`
 - `res.redirect([status,] path)` - Redirects to a specified path or URL. `status` must be a valid [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). If not specified, `status` defaults to "307" "Temporary redirect".
+- `res.unstable_revalidate(urlPath)` - [Revalidate a page on demand](/docs/basic-features/data-fetching/incremental-static-regeneration.md#on-demand-revalidation-beta) using `getStaticProps`. `urlPath` must be a `string`.
 
 ## Setting the status code of a response
 

docs/basic-features/data-fetching/client-side.md

@@ -68,3 +68,14 @@ function Profile() {
   )
 }
 ```
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+  <a href="/docs/routing/introduction.md">
+    <b>Routing:</b>
+    <small>Learn more about routing in Next.js.</small>
+  </a>
+</div>

docs/basic-features/data-fetching/get-server-side-props.md

@@ -47,8 +47,8 @@ Take the following example. An API route is used to fetch some data from a CMS.
 
 If your page contains frequently updating data, and you don’t need to pre-render the data, you can fetch the data on the [client side](/docs/basic-features/data-fetching/client-side.md). An example of this is user-specific data:
 
-- First, immediately show the page without data. Parts of the page can be pre-rendered using Static Generation. You can show loading states for missing data.
-- Then, fetch the data on the client side and display it when ready.
+- First, immediately show the page without data. Parts of the page can be pre-rendered using Static Generation. You can show loading states for missing data
+- Then, fetch the data on the client side and display it when ready
 
 This approach works well for user dashboard pages, for example. Because a dashboard is a private, user-specific page, SEO is not relevant and the page doesn’t need to be pre-rendered. The data is frequently updated, which requires request-time data fetching.
 
@@ -74,6 +74,14 @@ export async function getServerSideProps() {
 export default Page
 ```
 
+## Does getServerSideProps render an error page
+
+If an error is thrown inside `getServerSideProps`, it will show the `pages/500.js` file. Check out the documentation for [500 page](/docs/advanced-features/custom-error-page#500-page) to learn more on how to create it. During development this file will not be used and the dev overlay will be shown instead.
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
 <div class="card">
   <a href="/docs/api-reference/data-fetching/get-server-side-props.md">
     <b>getServerSideProps API Reference</b>

docs/basic-features/data-fetching/get-static-paths.md

@@ -19,7 +19,7 @@ export async function getStaticPaths() {
 }
 ```
 
-Note that`getStaticProps` **must** be used with `getStaticPaths`, and that you **cannot** use it with [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md).
+`getStaticPaths` **must** be used with `getStaticProps`. You **cannot** use it with [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md).
 
 The [`getStaticPaths` API reference](/docs/api-reference/data-fetching/get-static-paths.md) covers all parameters and props that can be used with `getStaticPaths`.
 
@@ -35,7 +35,11 @@ You should use `getStaticPaths` if you’re statically pre-rendering pages that
 
 ## When does getStaticPaths run
 
-`getStaticPaths` only runs at build time on server-side. If you're using [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md), `getStaticPaths` can also be run on-demand _in the background_, but still only on the server-side.
+`getStaticPaths` always runs on the server and never on the client. You can validate code written inside `getStaticPaths` is removed from the client-side bundle [with this tool](https://next-code-elimination.vercel.app/).
+
+- `getStaticPaths` runs during `next build` for Pages included in `paths`
+- `getStaticPaths` runs on-demand in the background when using `fallback: true`
+- `getStaticPaths` runs on-demand blocking rendering when using `fallback: blocking`
 
 ## Where can I use getStaticPaths
 
@@ -47,6 +51,10 @@ Note that you must use export `getStaticPaths` as a standalone function — it w
 
 In development (`next dev`), `getStaticPaths` will be called on every request.
 
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
 <div class="card">
   <a href="/docs/api-reference/data-fetching/get-static-paths.md">
     <b>getStaticPaths API Reference</b>