Skip to content

Commit 3c6f421

Browse files
styfleleerobtimneutkens
authored
Add docs for Image Optimization (#18107)
Co-authored-by: Lee Robinson <[email protected]> Co-authored-by: Tim Neutkens <[email protected]>
1 parent 301c029 commit 3c6f421

File tree

9 files changed

+334
-0
lines changed

9 files changed

+334
-0
lines changed

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

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
description: Enable image optimization with the built-in Image component.
3+
---
4+
5+
# next/image
6+
7+
<details>
8+
<summary><b>Examples</b></summary>
9+
<ul>
10+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/image-component">Image Component</a></li>
11+
</ul>
12+
</details>
13+
14+
> Before moving forward, we recommend you to read [Image Optimization](/docs/basic-features/image-optimization.md) first.
15+
16+
Image Optimization can be enabled via the `Image` component exported by `next/image`.
17+
18+
For an example, consider a project with the following files:
19+
20+
- `pages/index.js`
21+
- `public/me.png`
22+
23+
We can serve an optimized image like so:
24+
25+
```jsx
26+
import Image from 'next/image'
27+
28+
function Home() {
29+
return (
30+
<>
31+
<h1>My Homepage</h1>
32+
<Image src="/me.png" alt="me" width={200} height={200} />
33+
<p>Welcome to my homepage!</p>
34+
</>
35+
)
36+
}
37+
38+
export default Home
39+
```
40+
41+
`Image` accepts the following props:
42+
43+
- `src` - The path or URL to the source image. This is required.
44+
- `width` - The intrinsic width of the source image in pixels. Must be an integer without a unit. Required unless `unsized` is true.
45+
- `height` - The intrinsic height of the source image, in pixels. Must be an integer without a unit. Required unless `unsized` is true.
46+
- `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).
47+
- `quality` - The quality of the optimized image, an integer between 1 and 100 where 100 is the best quality. Default 100.
48+
- `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)
49+
- `priority` - When true, the image will be considered high priority and [preload](https://web.dev/preload-responsive-images/).
50+
- `unoptimized` - When true, the source image will be served as-is instead of resizing and changing quality.
51+
- `unsized` - When true, the `width` and `height` requirement can by bypassed. Should _not_ be used with `priority` or above-the-fold images.
52+
53+
Another other properties on the `<Image>` component be passed to the underlying `<img>` element.

‎docs/basic-features/image-optimization.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
description: Next.js supports built-in image optimization, as well as third party loaders for Imgix, Cloudinary, and more! Learn more here.
3+
---
4+
5+
# Image Optimization
6+
7+
<details open>
8+
<summary><b>Examples</b></summary>
9+
<ul>
10+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/image-component">Image Component</a></li>
11+
</ul>
12+
</details>
13+
14+
Since version **10.0.0** Next.js has a built-in Image Component and Automatic Image Optimization.
15+
16+
The Next.js Image Component (`next/image`) is an extension of the HTML `<img>` element, evolved for the modern web.
17+
18+
The Automatic Image Optimization allows for resizing, optimizing, and serving images in modern formats like [WebP](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types). This avoids shipping large images to devices with a smaller viewport.
19+
20+
## Image Component
21+
22+
To add an image to your application, import the `next/image` component:
23+
24+
```jsx
25+
import Image from 'next/image'
26+
27+
function Home() {
28+
return (
29+
<>
30+
<h1>My Homepage</h1>
31+
<Image
32+
src="/me.png"
33+
alt="Picture of the author"
34+
width={200}
35+
height={200}
36+
/>
37+
<p>Welcome to my homepage!</p>
38+
</>
39+
)
40+
}
41+
42+
export default Home
43+
```
44+
45+
- `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)
46+
- `width` and `height` are automatically responsive, unlike the HTML `<img>` element
47+
48+
## Configuration
49+
50+
You can configure Image Optimization by using the `images` property in `next.config.js`.
51+
52+
### Sizes
53+
54+
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.
55+
56+
```js
57+
module.exports = {
58+
images: {
59+
sizes: [320, 420, 768, 1024, 1200],
60+
},
61+
}
62+
```
63+
64+
### Domains
65+
66+
To enable Image Optimization for images hosted on an external website, use an absolute url for the Image `src` and specify which
67+
`domains` are allowed to be optimized. This is needed to ensure that external urls can't be abused.
68+
69+
```js
70+
module.exports = {
71+
images: {
72+
domains: ['example.com'],
73+
},
74+
}
75+
```
76+
77+
### Loader
78+
79+
If you want to use a cloud image provider to optimize images instead of using the Next.js' built-in image optimization, you can configure the loader and path prefix. This allows you to use relative urls for the Image `src` and automatically generate the correct absolute url for your provider.
80+
81+
```js
82+
module.exports = {
83+
images: {
84+
loader: 'imgix',
85+
path: 'https://example.com/myaccount/',
86+
},
87+
}
88+
```
89+
90+
The following Image Optimization cloud providers are supported:
91+
92+
- Imgix: `loader: 'imgix'`
93+
- Cloudinary: `loader: 'cloudinary'`
94+
- Akamai: `loader: 'akamai'`
95+
- Vercel: No configuration necessary
96+
97+
## Related
98+
99+
For more information on what to do next, we recommend the following sections:
100+
101+
<div class="card">
102+
<a href="/docs/basic-features/built-in-css-support.md">
103+
<b>CSS Support:</b>
104+
<small>Use the built-in CSS support to add custom styles to your app.</small>
105+
</a>
106+
</div>
107+
108+
<div class="card">
109+
- When using `next start` or a custom server image optimization works automatically.
110+
- [Vercel](https://vercel.com): Works automatically when you deploy on Vercel
111+
- [Imgix](https://www.imgix.com): `loader: 'imgix'`
112+
- [Cloudinary](https://cloudinary.com): `loader: 'cloudinary'`
113+
- [Akamai](https://www.akamai.com): `loader: 'akamai'`

‎examples/image-component/.gitignore‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.js
7+
8+
# testing
9+
/coverage
10+
11+
# next.js
12+
/.next/
13+
/out/
14+
15+
# production
16+
/build
17+
18+
# misc
19+
.DS_Store
20+
*.pem
21+
22+
# debug
23+
npm-debug.log*
24+
yarn-debug.log*
25+
yarn-error.log*
26+
27+
# local env files
28+
.env.local
29+
.env.development.local
30+
.env.test.local
31+
.env.production.local
32+
33+
# vercel
34+
.vercel

‎examples/image-component/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Image Component Example
2+
3+
This example shows how to use the [Image Component in Next.js](https://nextjs.org/docs/api-reference/next/image) serve optimized, responsive images.
4+
5+
The index page ([`pages/index.js`](pages/index.js)) has a couple images, one internal image and one external image. In [`next.config.js`](next.config.js), the `domains` property is used to enable external images. Run or deploy the app to see how it works!
6+
7+
## Deploy your own
8+
9+
Deploy the example using [Vercel](https://vercel.com):
10+
11+
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/import/project?template=https://github.com/vercel/next.js/tree/canary/examples/image-component)
12+
13+
## How to use
14+
15+
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:
16+
17+
```bash
18+
npx create-next-app --example image-component image-app
19+
# or
20+
yarn create next-app --example image-component image-app
21+
```
22+
23+
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)).

‎examples/image-component/next.config.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
module.exports = {
2+
images: {
3+
domains: ['assets.vercel.com'],
4+
},
5+
}

‎examples/image-component/package.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"name": "rewrites",
3+
"version": "1.0.0",
4+
"scripts": {
5+
"dev": "next dev",
6+
"build": "next build",
7+
"start": "next start"
8+
},
9+
"dependencies": {
10+
"next": "latest",
11+
"react": "^16.13.1",
12+
"react-dom": "^16.13.1"
13+
},
14+
"license": "MIT"
15+
}

‎examples/image-component/pages/index.js‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
import styles from '../styles.module.css'
2+
import Image from 'next/image'
3+
4+
const Code = (p) => <code className={styles.inlineCode} {...p} />
5+
6+
const Index = () => (
7+
<div className={styles.container}>
8+
<div className={styles.card}>
9+
<h1>Image Component with Next.js</h1>
10+
<p>
11+
The images below use the{' '}
12+
<a href="https://nextjs.org/docs/api-reference/next/image">
13+
&lt;Image&gt;
14+
</a>{' '}
15+
component to ensure optimal format and size for this browser.
16+
</p>
17+
<p>
18+
Images are also lazy loaded by default which means they don't load until
19+
scrolled into view.
20+
</p>
21+
<p>Try scolling down to try it out!</p>
22+
<hr className={styles.hr} />
23+
<p>
24+
The following is an example of a reference to an interal image from the{' '}
25+
<Code>public</Code> directory.
26+
</p>
27+
<p>
28+
Notice that the image is responsive. As you adjust your browser width, a
29+
different sized image is loaded.
30+
</p>
31+
<Image alt="Vercel logo" src="/vercel.png" width={1000} height={1000} />
32+
<hr className={styles.hr} />
33+
<p>
34+
The following is an example of a reference to an external image at{' '}
35+
<Code>assets.vercel.com</Code>.
36+
</p>
37+
<p>
38+
External domains must be configured in <Code>next.config.js</Code> using
39+
the <Code>domains</Code>.
40+
</p>
41+
<Image
42+
alt="Next.js logo"
43+
src="https://assets.vercel.com/image/upload/v1538361091/repositories/next-js/next-js.png"
44+
width={1200}
45+
height={400}
46+
/>
47+
<hr className={styles.hr} />
48+
Checkout the documentation for{' '}
49+
<a href="https://nextjs.org/docs/basic-features/data-fetching">
50+
Image Optimization
51+
</a>{' '}
52+
to learn more.
53+
</div>
54+
</div>
55+
)
56+
57+
export default Index

‎examples/image-component/public/vercel.png‎

29.4 KB
Loading

‎examples/image-component/styles.module.css‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.container {
2+
padding: 4rem 1rem;
3+
font-family: -apple-system, BlinkMacSystemFont, sans-serif;
4+
}
5+
6+
.container p {
7+
margin: 1.5rem 0;
8+
}
9+
10+
.card {
11+
max-width: 50rem;
12+
box-shadow: -10px 10px 80px rgba(0, 0, 0, 0.12);
13+
border: 1px solid #eee;
14+
border-radius: 8px;
15+
padding: 2rem;
16+
margin: 0 auto;
17+
}
18+
19+
.inlineCode {
20+
color: #be00ff;
21+
font-size: 16px;
22+
white-space: pre-wrap;
23+
}
24+
25+
.inlineCode::before,
26+
.inlineCode::after {
27+
content: '`';
28+
}
29+
30+
.hr {
31+
border: 0;
32+
border-top: 1px solid #eaeaea;
33+
margin: 1.5rem 0;
34+
}

0 commit comments

Comments
 (0)