Skip to content

Commit

Permalink
Update docs for remotePatterns image config (#40350)
Browse files Browse the repository at this point in the history
This updates the docs to favor `remotePatterns` image config (instead of `domains`)
  • Loading branch information
styfle authored Sep 8, 2022
1 parent 66834d5 commit 712d98d
Show file tree
Hide file tree
Showing 3 changed files with 12 additions and 8 deletions.
4 changes: 3 additions & 1 deletion docs/api-reference/next/future/image.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,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

Expand Down Expand Up @@ -430,6 +430,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.
Expand Down
4 changes: 3 additions & 1 deletion docs/api-reference/next/image.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
12 changes: 6 additions & 6 deletions docs/basic-features/image-optimization.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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.

Expand Down Expand Up @@ -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)

Expand Down

0 comments on commit 712d98d

Please sign in to comment.