Merge branch 'canary' into feat/configurable-dynamic-guards

docs/advanced-features/middleware.md

@@ -31,7 +31,7 @@ To begin using Middleware, follow the steps below:
 npm install next@latest
 ```
 
-2. Create a `middleware.ts` (or `.js`) file at the same level as your `pages` directory
+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

docs/api-reference/next/future/image.md

@@ -7,11 +7,11 @@ description: Try the latest Image Optimization with the new `next/future/image`
 <details>
   <summary><b>Version History</b></summary>
 
-| Version   | Changes                                                                                                                     |
-| --------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `v12.3.0` | `next/future/image` component stable. `remotePatterns` config stable. `unoptimized` config stable. `alt` property required. |
-| `v12.2.4` | `fill` property added.                                                                                                      |
-| `v12.2.0` | Experimental `next/future/image` component introduced.                                                                      |
+| Version   | Changes                                                                                                                                                          |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `v12.3.0` | `next/future/image` component stable. `remotePatterns` config stable. `unoptimized` config stable. `alt` property required. `onLoadingComplete` receives `<img>` |
+| `v12.2.4` | `fill` property added.                                                                                                                                           |
+| `v12.2.0` | Experimental `next/future/image` component introduced.                                                                                                           |
 
 </details>
 
@@ -33,6 +33,7 @@ Compared to `next/image`, the new `next/future/image` component has the followin
   - 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
+- Changed `onLoadingComplete` callback to receive reference to `<img>` element
 
 ## Known Browser Bugs
 
@@ -151,7 +152,7 @@ Must be one of the following:
 2. A path string. This can be either an absolute external URL,
    or an internal path depending on the [loader](#loader) prop.
 
-When using an external URL, you must add it to [domains](#domains) in `next.config.js`.
+When using an external URL, you must add it to [remotePatterns](#remote-patterns) in `next.config.js`.
 
 ### width
 
@@ -306,10 +307,7 @@ Also keep in mind that the required `width` and `height` props can interact with
 
 A callback function that is invoked once the image is completely loaded and the [placeholder](#placeholder) has been removed.
 
-The callback function will be called with one argument, an object with the following properties:
-
-- [`naturalWidth`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/naturalWidth)
-- [`naturalHeight`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/naturalHeight)
+The callback function will be called with one argument, a reference to the underlying `<img>` element.
 
 ### onLoad
 
@@ -430,6 +428,8 @@ The `**` syntax does not work in the middle of the pattern.
 
 ### Domains
 
+> Note: We recommend using [`remotePatterns`](#remote-patterns) instead so you can restrict protocol and pathname.
+
 Similar to [`remotePatterns`](#remote-patterns), the `domains` configuration can be used to provide a list of allowed hostnames for external images.
 
 However, the `domains` configuration does not support wildcard pattern matching and it cannot restrict protocol, port, or pathname.

docs/api-reference/next/image.md

@@ -45,7 +45,7 @@ Must be one of the following:
    or an internal path depending on the [loader](#loader) prop or [loader configuration](#loader-configuration).
 
 When using an external URL, you must add it to
-[domains](#domains) in
+[remotePatterns](#remote-patterns) in
 `next.config.js`.
 
 ### width
@@ -393,6 +393,8 @@ The `**` syntax does not work in the middle of the pattern.
 
 ### Domains
 
+> Note: We recommend using [`remotePatterns`](#remote-patterns) instead so you can restrict protocol and pathname.
+
 Similar to [`remotePatterns`](#remote-patterns), the `domains` configuration can be used to provide a list of allowed hostnames for external images.
 
 However, the `domains` configuration does not support wildcard pattern matching and it cannot restrict protocol, port, or pathname.

docs/basic-features/image-optimization.md

@@ -72,7 +72,7 @@ function Home() {
 
 ### Remote Images
 
-To use a remote image, the `src` property should be a URL string, which can be [relative](#loaders) or [absolute](/docs/api-reference/next/image.md#domains). Because Next.js does not have access to remote files during the build process, you'll need to provide the [`width`](/docs/api-reference/next/image.md#width), [`height`](/docs/api-reference/next/image.md#height) and optional [`blurDataURL`](/docs/api-reference/next/image.md#blurdataurl) props manually:
+To use a remote image, the `src` property should be a URL string, which can be [relative](#loaders) or [absolute](/docs/api-reference/next/image.md#remote-patterns). Because Next.js does not have access to remote files during the build process, you'll need to provide the [`width`](/docs/api-reference/next/image.md#width), [`height`](/docs/api-reference/next/image.md#height) and optional [`blurDataURL`](/docs/api-reference/next/image.md#blurdataurl) props manually:
 
 ```jsx
 import Image from 'next/image'
@@ -97,17 +97,17 @@ export default function Home() {
 
 ### Domains
 
-Sometimes you may want to access a remote image, but still use the built-in Next.js Image Optimization API. To do this, leave the `loader` at its default setting and enter an absolute URL for the Image `src`.
+Sometimes you may want to optimize a remote image, but still use the built-in Next.js Image Optimization API. To do this, leave the `loader` at its default setting and enter an absolute URL for the Image `src` prop.
 
-To protect your application from malicious users, you must define a list of remote hostnames you intend to allow remote access.
+To protect your application from malicious users, you must define a list of remote hostnames you intend to use with the `next/image` component.
 
-> Learn more about [`domains`](/docs/api-reference/next/image.md#domains) configuration.
+> Learn more about [`remotePatterns`](/docs/api-reference/next/image.md#remote-patterns) configuration.
 
 ### Loaders
 
 Note that in the [example earlier](#remote-images), a partial URL (`"/me.png"`) is provided for a remote image. This is possible because of the `next/image` [loader](/docs/api-reference/next/image.md#loader) architecture.
 
-A loader is a function that generates the URLs for your image. It appends a root domain to your provided `src`, and generates multiple URLs to request the image at different sizes. These multiple URLs are used in the automatic [srcset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset) generation, so that visitors to your site will be served an image that is the right size for their viewport.
+A loader is a function that generates the URLs for your image. It modifies the provided `src`, and generates multiple URLs to request the image at different sizes. These multiple URLs are used in the automatic [srcset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset) generation, so that visitors to your site will be served an image that is the right size for their viewport.
 
 The default loader for Next.js applications uses the built-in Image Optimization API, which optimizes images from anywhere on the web, and then serves them directly from the Next.js web server. If you would like to serve your images directly from a CDN or image server, you can use one of the [built-in loaders](/docs/api-reference/next/image.md#built-in-loaders) or write your own with a few lines of JavaScript.
 
@@ -209,7 +209,7 @@ For examples of the Image component used with the various fill modes, see the [I
 
 ## Configuration
 
-The `next/image` component and Next.js Image Optimization API can be configured in the [`next.config.js` file](/docs/api-reference/next.config.js/introduction.md). These configurations allow you to [enable remote images](/docs/api-reference/next/image.md#domains), [define custom image breakpoints](/docs/api-reference/next/image.md#device-sizes), [change caching behavior](/docs/api-reference/next/image.md#caching-behavior) and more.
+The `next/image` component and Next.js Image Optimization API can be configured in the [`next.config.js` file](/docs/api-reference/next.config.js/introduction.md). These configurations allow you to [enable remote images](/docs/api-reference/next/image.md#remote-patterns), [define custom image breakpoints](/docs/api-reference/next/image.md#device-sizes), [change caching behavior](/docs/api-reference/next/image.md#caching-behavior) and more.
 
 [**Read the full image configuration documentation for more information.**](/docs/api-reference/next/image.md#configuration-options)
 

docs/going-to-production.md

@@ -72,7 +72,7 @@ export async function getServerSideProps({ req, res }) {
 By default, `Cache-Control` headers will be set differently depending on how your page fetches data.
 
 - If the page uses `getServerSideProps` or `getInitialProps`, it will use the default `Cache-Control` header set by `next start` in order to prevent accidental caching of responses that cannot be cached. If you want a different cache behavior while using `getServerSideProps`, use `res.setHeader('Cache-Control', 'value_you_prefer')` inside of the function as shown above.
-- If the page is using `getStaticProps`, it will have a `Cache-Control` header of `s-maxage=REVALIDATE_SECONDS, stale-while-revalidate`, or if `revalidate` is _not_ used , `s-maxage=31536000, stale-while-revalidate` to cache for the maximum age possible.
+- If the page is using `getStaticProps`, it will have a `Cache-Control` header of `s-maxage=REVALIDATE_SECONDS, stale-while-revalidate`, or if `revalidate` is _not_ used, `s-maxage=31536000, stale-while-revalidate` to cache for the maximum age possible.
 
 > **Note:** Your deployment provider must support caching for dynamic responses. If you are self-hosting, you will need to add this logic yourself using a key/value store like Redis. If you are using Vercel, [Edge Caching works without configuration](https://vercel.com/docs/edge-network/caching?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).
 
@@ -90,7 +90,7 @@ To reduce the amount of JavaScript sent to the browser, you can use the followin
 - [Import Cost](https://marketplace.visualstudio.com/items?itemName=wix.vscode-import-cost) – Display the size of the imported package inside VSCode.
 - [Package Phobia](https://packagephobia.com/) – Find the cost of adding a new dev dependency to your project.
 - [Bundle Phobia](https://bundlephobia.com/) - Analyze how much a dependency can increase bundle sizes.
-- [Webpack Bundle Analyzer](https://github.com/vercel/next.js/tree/canary/packages/next-bundle-analyzer) – Visualize size of webpack output files with an interactive, zoomable treemap.
+- [Webpack Bundle Analyzer](https://github.com/vercel/next.js/tree/canary/packages/next-bundle-analyzer) – Visualize the size of webpack output files with an interactive, zoomable treemap.
 - [bundlejs](https://bundlejs.com/) - An online tool to quickly bundle & minify your projects, while viewing the compressed gzip/brotli bundle size, all running locally on your browser.
 
 Each file inside your `pages/` directory will automatically be code split into its own JavaScript bundle during `next build`. You can also use [Dynamic Imports](/docs/advanced-features/dynamic-import.md) to lazy-load components and libraries. For example, you might want to defer loading your modal code until a user clicks the open button.
@@ -142,7 +142,7 @@ Once you are able to measure the loading performance, use the following strategi
   - Setting up your Code Editor to view import costs and sizes
   - Finding alternative smaller packages
   - Dynamically loading components and dependencies
-  - For more in depth information, review this [guide](https://papyrus.dev/@PapyrusBlog/how-we-reduced-next.js-page-size-by-3.5x-and-achieved-a-98-lighthouse-score) and this [performance checklist](https://dev.to/endymion1818/nextjs-performance-checklist-5gjb).
+  - For more in-depth information, review this [guide](https://papyrus.dev/@PapyrusBlog/how-we-reduced-next.js-page-size-by-3.5x-and-achieved-a-98-lighthouse-score) and this [performance checklist](https://dev.to/endymion1818/nextjs-performance-checklist-5gjb).
 
 ## Related
 

docs/migrating/incremental-adoption.md

@@ -92,4 +92,4 @@ Once your monorepo is set up, push changes to your Git repository as usual and y
 
 ## 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.jsmonorepo](https://vercel.com/templates/next.js/monorepo).
+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).

docs/testing.md

@@ -145,7 +145,7 @@ Playwright is a testing framework that lets you automate Chromium, Firefox, and
 
 ### 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.
+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
@@ -214,7 +214,7 @@ test('should navigate to the about page', async ({ page }) => {
   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)
+  // 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')
@@ -307,7 +307,7 @@ Under the hood, `next/jest` is automatically configuring Jest for you, including
 
 ### 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.
+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:
 
@@ -440,7 +440,7 @@ Add the Jest executable in watch mode to the `package.json` scripts:
 
 **Create your first tests**
 
-Your project is now ready to run tests. Follow Jests convention by adding tests to the `__tests__` folder in your project's root directory.
+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 `<Home />` component successfully renders a heading: