Merge remote-tracking branch 'upstream/canary' into example/i18n

Author: ijjk

docs/api-reference/next/image.md

@@ -1,5 +1,5 @@
 ---
-description: Enable image optimization with the built-in Image component.
+description: Enable Image Optimization with the built-in Image component.
 ---
 
 # next/image
@@ -29,7 +29,12 @@ function Home() {
   return (
     <>
       <h1>My Homepage</h1>
-      <Image src="/me.png" alt="me" width={200} height={200} />
+      <Image
+        src="/me.png"
+        alt="Picture of the author"
+        width={500}
+        height={500}
+      />
       <p>Welcome to my homepage!</p>
     </>
   )
@@ -48,6 +53,6 @@ export default Home
 - `loading` - The loading behavior. When `lazy`, defer loading the image until it reaches a calculated distance from the viewport. When `eager`, load the image immediately. Default `lazy`. [More info](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading)
 - `priority` - When true, the image will be considered high priority and [preload](https://web.dev/preload-responsive-images/).
 - `unoptimized` - When true, the source image will be served as-is instead of resizing and changing quality.
-- `unsized` - When true, the `width` and `height` requirement can by bypassed. Should _not_ be used with `priority` or above-the-fold images.
+- `unsized` - When true, the `width` and `height` requirement can by bypassed. Should _not_ be used with above-the-fold images. Should _not_ be used with `priority`.
 
-Another other properties on the `<Image>` component be passed to the underlying `<img>` element.
+All other properties on the `<Image>` component will be passed to the underlying `<img>` element.

docs/basic-features/image-optimization.md

@@ -2,7 +2,7 @@
 description: Next.js supports built-in image optimization, as well as third party loaders for Imgix, Cloudinary, and more! Learn more here.
 ---
 
-# Image Optimization
+# Image Component and Image Optimization
 
 <details open>
   <summary><b>Examples</b></summary>
@@ -19,7 +19,7 @@ The Automatic Image Optimization allows for resizing, optimizing, and serving im
 
 ## Image Component
 
-To add an image to your application, import the `next/image` component:
+To add an image to your application, import the [`next/image`](/docs/api-reference/next/image.md) component:
 
 ```jsx
 import Image from 'next/image'
@@ -31,8 +31,8 @@ function Home() {
       <Image
         src="/me.png"
         alt="Picture of the author"
-        width={200}
-        height={200}
+        width={500}
+        height={500}
       />
       <p>Welcome to my homepage!</p>
     </>
@@ -44,19 +44,32 @@ export default Home
 
 - `width` and `height` are required to prevent [Cumulative Layout Shift](https://web.dev/cls/), a [Core Web Vital](https://web.dev/vitals/) that Google is going to [use in their search ranking](https://webmasters.googleblog.com/2020/05/evaluating-page-experience.html)
 - `width` and `height` are automatically responsive, unlike the HTML `<img>` element
+- See [`next/image`](/docs/api-reference/next/image.md) for list of available props.
 
 ## Configuration
 
 You can configure Image Optimization by using the `images` property in `next.config.js`.
 
-### Sizes
+### Device Sizes
 
-You can specify a list of image widths to allow using the `sizes` property. Since images maintain their aspect ratio using the `width` and `height` attributes of the source image, there is no need to specify height in `next.config.js` – only the width. You can think of these as breakpoints.
+You can specify a list of device width breakpoints using the `deviceSizes` property. Since images maintain their aspect ratio using the `width` and `height` attributes of the source image, there is no need to specify height in `next.config.js` – only the width. These values will be used by the browser to determine which size image should load.
 
 ```js
 module.exports = {
   images: {
-    sizes: [320, 420, 768, 1024, 1200],
+    deviceSizes: [320, 420, 768, 1024, 1200],
+  },
+}
+```
+
+### Icon Sizes
+
+You can specify a list of icon image widths using the `iconSizes` property. These widths should be smaller than the smallest value in `deviceSizes`. The purpose is for images that don't scale with the browser window, such as icons or badges. If `iconSizes` is not defined, then `deviceSizes` will be used.
+
+```js
+module.exports = {
+  images: {
+    iconSizes: [16, 32, 64],
   },
 }
 ```
@@ -89,25 +102,19 @@ module.exports = {
 
 The following Image Optimization cloud providers are supported:
 
-- Imgix: `loader: 'imgix'`
-- Cloudinary: `loader: 'cloudinary'`
-- Akamai: `loader: 'akamai'`
-- Vercel: No configuration necessary
+- When using `next start` or a custom server image optimization works automatically.
+- [Vercel](https://vercel.com): Works automatically when you deploy on Vercel
+- [Imgix](https://www.imgix.com): `loader: 'imgix'`
+- [Cloudinary](https://cloudinary.com): `loader: 'cloudinary'`
+- [Akamai](https://www.akamai.com): `loader: 'akamai'`
 
 ## Related
 
 For more information on what to do next, we recommend the following sections:
 
 <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 href="/docs/api-reference/next/image.md">
+    <b>next/image</b>
+    <small>See all available properties for the Image component</small>
   </a>
 </div>
-
-<div class="card">
-- When using `next start` or a custom server image optimization works automatically.
-- [Vercel](https://vercel.com): Works automatically when you deploy on Vercel
-- [Imgix](https://www.imgix.com): `loader: 'imgix'`
-- [Cloudinary](https://cloudinary.com): `loader: 'cloudinary'`
-- [Akamai](https://www.akamai.com): `loader: 'akamai'`

docs/manifest.json

@@ -21,6 +21,10 @@
               "title": "Built-in CSS Support",
               "path": "/docs/basic-features/built-in-css-support.md"
             },
+            {
+              "title": "Image Optimization",
+              "path": "/docs/basic-features/image-optimization.md"
+            },
             {
               "title": "Fast Refresh",
               "path": "/docs/basic-features/fast-refresh.md"
@@ -216,6 +220,10 @@
           "title": "next/link",
           "path": "/docs/api-reference/next/link.md"
         },
+        {
+          "title": "next/image",
+          "path": "/docs/api-reference/next/image.md"
+        },
         {
           "title": "next/head",
           "path": "/docs/api-reference/next/head.md"

lerna.json

@@ -17,5 +17,5 @@
       "registry": "https://registry.npmjs.org/"
     }
   },
-  "version": "9.5.6-canary.13"
+  "version": "9.5.6-canary.16"
 }

packages/create-next-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-next-app",
-  "version": "9.5.6-canary.13",
+  "version": "9.5.6-canary.16",
   "keywords": [
     "react",
     "next",

packages/eslint-plugin-next/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/eslint-plugin-next",
-  "version": "9.5.6-canary.13",
+  "version": "9.5.6-canary.16",
   "description": "ESLint plugin for NextJS.",
   "main": "lib/index.js",
   "license": "MIT",

packages/next-bundle-analyzer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/bundle-analyzer",
-  "version": "9.5.6-canary.13",
+  "version": "9.5.6-canary.16",
   "main": "index.js",
   "license": "MIT",
   "repository": {

packages/next-codemod/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/codemod",
-  "version": "9.5.6-canary.13",
+  "version": "9.5.6-canary.16",
   "license": "MIT",
   "dependencies": {
     "chalk": "4.1.0",

packages/next-env/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/env",
-  "version": "9.5.6-canary.13",
+  "version": "9.5.6-canary.16",
   "keywords": [
     "react",
     "next",

packages/next-mdx/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/mdx",
-  "version": "9.5.6-canary.13",
+  "version": "9.5.6-canary.16",
   "main": "index.js",
   "license": "MIT",
   "repository": {