Merge branch 'ch13148/image-docs' of github.com:vercel/next.js into vercel-ch13148/image-docs

timneutkens · timneutkens · commit e1858bb5dd50 · 2020-10-23T23:16:42.000+02:00
# Conflicts:
#	docs/basic-features/image-optimization.md
diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md
@@ -7,7 +7,7 @@ description: Enable image optimization with the built-in Image component.
 <details>
   <summary><b>Examples</b></summary>
   <ul>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/basic-image-optimization">Basic Image Optimization</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/image-component">Image Component</a></li>
   </ul>
 </details>
 
@@ -41,10 +41,13 @@ export default Home
 `Image` accepts the following props:
 
 - `src` - The path or URL to the source image. This is required.
-- `width` - The width of the source image. This is recommended and required unless `unsized` is true.
-- `height` - The height of the source image. This is recommended and required unless `unsized` is true.
-- `quality` - The quality of the optimized image, an integer between 1 and 100 where 100 is the best quality.
-- `lazy` - When true, the image will not load until scrolled into the viewport.
-- `priority` - When true, the image will be considered high priority and preload.
+- `width` - The intrinsic width of the source image in pixels. Must be an integer without a unit. Required unless `unsized` is true.
+- `height` - The intrinsic height of the source image, in pixels. Must be an integer without a unit. Required unless `unsized` is true.
+- `sizes` - Defines what proportion of the screen you expect the image to take up. Recommended, as it helps serve the correct sized image to each device. [More info](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes).
+- `quality` - The quality of the optimized image, an integer between 1 and 100 where 100 is the best quality. Default 100.
+- `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 `priority` or above-the-fold images.
+
+Another other properties on the `<Image>` component be passed to the underlying `<img>` element.
diff --git a/docs/basic-features/image-optimization.md b/docs/basic-features/image-optimization.md
@@ -7,7 +7,7 @@ description: Next.js supports built-in image optimization, as well as third part
 <details open>
   <summary><b>Examples</b></summary>
   <ul>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/basic-image-optimization">Basic Image Optimization</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/image-component">Image Component</a></li>
   </ul>
 </details>
 
@@ -89,6 +89,23 @@ module.exports = {
 
 The following Image Optimization cloud providers are supported:
 
+- Imgix: `loader: 'imgix'`
+- Cloudinary: `loader: 'cloudinary'`
+- Akamai: `loader: 'akamai'`
+- Vercel: No configuration necessary
+
+## 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>
+</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'`
diff --git a/examples/image-component/.gitignore b/examples/image-component/.gitignore
@@ -0,0 +1,34 @@
+# 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
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel
diff --git a/examples/image-component/README.md b/examples/image-component/README.md
@@ -0,0 +1,23 @@
+# Rewrites Example
+
+This example shows how to use [rewrites in Next.js](https://nextjs.org/docs/api-reference/next.config.js/rewrites) to map an incoming request path to a different destination path.
+
+The index page ([`pages/index.js`](pages/index.js)) has a list of links that match the rewrites defined in [`next.config.js`](next.config.js). Run or deploy the app to see how it works!
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com):
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/import/project?template=https://github.com/vercel/next.js/tree/canary/examples/rewrites)
+
+## 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 rewrites rewrites-app
+# or
+yarn create next-app --example rewrites rewrites-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
diff --git a/examples/image-component/next.config.js b/examples/image-component/next.config.js
@@ -0,0 +1,5 @@
+module.exports = {
+  images: {
+    domains: ['assets.vercel.com'],
+  },
+}
diff --git a/examples/image-component/package.json b/examples/image-component/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "rewrites",
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "latest",
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1"
+  },
+  "license": "MIT"
+}
diff --git a/examples/image-component/pages/index.js b/examples/image-component/pages/index.js
@@ -0,0 +1,56 @@
+import styles from '../styles.module.css'
+import Image from 'next/image'
+
+const Code = (p) => <code className={styles.inlineCode} {...p} />
+
+const Index = () => (
+  <div className={styles.container}>
+    <div className={styles.card}>
+      <h1>Image Component with Next.js</h1>
+      <p>
+        The images below use the{' '}
+        <a href="https://nextjs.org/docs/api-reference/next/image">
+          &lt;Image&gt;
+        </a>{' '}
+        component to ensure optimal format and size for this browser.
+      </p>
+      <p>
+        Images are also lazy loaded by default which means they don't load until
+        scrolled into view.
+      </p>
+      <p>Try scolling down to try it out!</p>
+      <hr className={styles.hr} />
+      <p>
+        The following is an example of a reference to an interal image from the{' '}
+        <Code>public</Code> directory.
+      </p>
+      <p>
+        Notice that the image is responsive. As you adjust your browser width, a
+        different sized image is loaded.
+      </p>
+      <Image src="/vercel.png" width={1000} height={1000} />
+      <hr className={styles.hr} />
+      <p>
+        The following is an example of a reference to an external image at{' '}
+        <Code>assets.vercel.com</Code>.
+      </p>
+      <p>
+        External domains must be configured in <Code>next.config.js</Code> using
+        the <Code>domains</Code>.
+      </p>
+      <Image
+        src="https://assets.vercel.com/image/upload/v1538361091/repositories/next-js/next-js.png"
+        width={1200}
+        height={400}
+      />
+      <hr className={styles.hr} />
+      Checkout the documentation for{' '}
+      <a href="https://nextjs.org/docs/basic-features/data-fetching">
+        Image Optimization
+      </a>{' '}
+      to learn more.
+    </div>
+  </div>
+)
+
+export default Index
diff --git a/examples/image-component/public/vercel.png b/examples/image-component/public/vercel.png
diff --git a/examples/image-component/styles.module.css b/examples/image-component/styles.module.css
@@ -0,0 +1,34 @@
+.container {
+  padding: 4rem 1rem;
+  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+}
+
+.container p {
+  margin: 1.5rem 0;
+}
+
+.card {
+  max-width: 50rem;
+  box-shadow: -10px 10px 80px rgba(0, 0, 0, 0.12);
+  border: 1px solid #eee;
+  border-radius: 8px;
+  padding: 2rem;
+  margin: 0 auto;
+}
+
+.inlineCode {
+  color: #be00ff;
+  font-size: 16px;
+  white-space: pre-wrap;
+}
+
+.inlineCode::before,
+.inlineCode::after {
+  content: '`';
+}
+
+.hr {
+  border: 0;
+  border-top: 1px solid #eaeaea;
+  margin: 1.5rem 0;
+}
