Unverified Commit cbda3b52 authored by Balázs Orbán's avatar Balázs Orbán Committed by GitHub

docs(image): improve error message when `sharp` is missing in standalone mode (#41133)

Partially addresses #41111

## Bug

- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have a helpful link attached, see `contributing.md`

## Feature

- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have a helpful link attached, see `contributing.md`

## Documentation / Examples

- [ ] Make sure the linting passes by running `pnpm lint`
- [ ] The "examples guidelines" are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md)
Co-authored-by: 's avatarJJ Kasper <22380829+ijjk@users.noreply.github.com>
parent 99d88f2a
...@@ -16,11 +16,11 @@ During `next build`, Next.js will use [`@vercel/nft`](https://github.com/vercel/ ...@@ -16,11 +16,11 @@ During `next build`, Next.js will use [`@vercel/nft`](https://github.com/vercel/
Next.js' production server is also traced for its needed files and output at `.next/next-server.js.nft.json` which can be leveraged in production. Next.js' production server is also traced for its needed files and output at `.next/next-server.js.nft.json` which can be leveraged in production.
To leverage the `.nft.json` files emitted to the `.next` output directory, you can read the list of files in each trace which are relative to the `.nft.json` file and then copy them to your deployment location. To leverage the `.nft.json` files emitted to the `.next` output directory, you can read the list of files in each trace that are relative to the `.nft.json` file and then copy them to your deployment location.
## Automatically Copying Traced Files ## Automatically Copying Traced Files
Next.js can automatically create a `standalone` folder which copies only the necessary files for a production deployment including select files in `node_modules`. Next.js can automatically create a `standalone` folder that copies only the necessary files for a production deployment including select files in `node_modules`.
To leverage this automatic copying you can enable it in your `next.config.js`: To leverage this automatic copying you can enable it in your `next.config.js`:
...@@ -30,12 +30,26 @@ module.exports = { ...@@ -30,12 +30,26 @@ module.exports = {
} }
``` ```
This will create a folder at `.next/standalone` which can then be deployed on it's own without installing `node_modules`. This will create a folder at `.next/standalone` which can then be deployed on its own without installing `node_modules`.
Additionally, a minimal `server.js` file is also output which can be used instead of `next start`. This minimal server does not copy the `public` or `.next/static` folders by default as these should ideally be handled by a CDN instead, although these folders can be copied to the `standalone/public` and `standalone/.next/static` folders manually, after which `server.js` file will serve these automatically. Additionally, a minimal `server.js` file is also output which can be used instead of `next start`. This minimal server does not copy the `public` or `.next/static` folders by default as these should ideally be handled by a CDN instead, although these folders can be copied to the `standalone/public` and `standalone/.next/static` folders manually, after which `server.js` file will serve these automatically.
Note: `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/api-reference/next.config.js/runtime-configuration.md) are being used, the values will be specific to values at build time. Note: `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/api-reference/next.config.js/runtime-configuration.md) are being used, the values will be specific to values at build time.
If your project uses [Image Optimization](/docs/basic-features/image-optimization.md) with the default `loader`, you must install `sharp` as a dependency:
```bash
npm i sharp
```
```bash
yarn add sharp
```
```bash
pnpm add sharp
```
## Caveats ## Caveats
- While tracing in monorepo setups, the project directory is used for tracing by default. For `next build packages/web-app`, `packages/web-app` would be the tracing root and any files outside of that folder will not be included. To include files outside of this folder you can set `experimental.outputFileTracingRoot` in your `next.config.js`. - While tracing in monorepo setups, the project directory is used for tracing by default. For `next build packages/web-app`, `packages/web-app` would be the tracing root and any files outside of that folder will not be included. To include files outside of this folder you can set `experimental.outputFileTracingRoot` in your `next.config.js`.
...@@ -50,5 +64,5 @@ module.exports = { ...@@ -50,5 +64,5 @@ module.exports = {
} }
``` ```
- There are some cases that Next.js might fail to include required files, or might incorrectly include unused files. In those cases, you can export page configs props `unstable_includeFiles` and `unstable_excludeFiles` respectively. Each prop accepts an array of [minimatch globs](https://www.npmjs.com/package/minimatch) relative to the project's root to either include or exclude in the trace. - There are some cases in which Next.js might fail to include required files, or might incorrectly include unused files. In those cases, you can export page configs props `unstable_includeFiles` and `unstable_excludeFiles` respectively. Each prop accepts an array of [minimatch globs](https://www.npmjs.com/package/minimatch) relative to the project's root to either include or exclude in the trace.
- Currently, Next.js does not do anything with the emitted `.nft.json` files. The files must be read by your deployment platform, for example [Vercel](https://vercel.com), to create a minimal deployment. In a future release, a new command is planned to utilize these `.nft.json` files. - Currently, Next.js does not do anything with the emitted `.nft.json` files. The files must be read by your deployment platform, for example [Vercel](https://vercel.com), to create a minimal deployment. In a future release, a new command is planned to utilize these `.nft.json` files.
...@@ -2,14 +2,35 @@ ...@@ -2,14 +2,35 @@
#### Why This Error Occurred #### Why This Error Occurred
The `next/image` component's default loader uses [`squoosh`](https://www.npmjs.com/package/@squoosh/lib) because it is quick to install and suitable for a development environment. For a production environment using `next start`, it is strongly recommended you install [`sharp`](https://www.npmjs.com/package/sharp) by running `yarn add sharp` in your project directory. The `next/image` component's default loader uses [`squoosh`](https://www.npmjs.com/package/@squoosh/lib) because it is quick to install and suitable for a development environment.
- For a production environment using `next start`, it is strongly recommended you install [`sharp`](https://www.npmjs.com/package/sharp).
You are seeing this error because Image Optimization in production mode (`next start`) was detected. You are seeing this error because Image Optimization in production mode (`next start`) was detected.
- For a production environment using `output: "standalone"`, you must install [`sharp`](https://www.npmjs.com/package/sharp).
You are seeing this error because Image Optimization in standalone mode (`output: "standalone"`) was detected.
#### Possible Ways to Fix It #### Possible Ways to Fix It
- Install `sharp` by running `yarn add sharp` in your project directory and then reboot the server by running `next start` again - Install `sharp` by running one of the following commands in your project directory:
- If `sharp` is already installed but can't be resolved, set the `NEXT_SHARP_PATH` environment variable such as `NEXT_SHARP_PATH=/tmp/node_modules/sharp next start`
```bash
npm i sharp
```
```bash
yarn add sharp
```
```bash
pnpm add sharp
```
Then, build your project with `next build`. Finally, restart the server with either `next start` for production mode or `node server.js` for standalone mode.
- If `sharp` is already installed but can't be resolved, set the `NEXT_SHARP_PATH` environment variable such as `export NEXT_SHARP_PATH=/tmp/node_modules/sharp`. Then, build your project with `next build`. Finally, restart the server with either `next start` for production mode or `node server.js` for standalone mode.
> Note: This is not necessary for Vercel deployments, since `sharp` is installed automatically for you. > Note: This is not necessary for Vercel deployments, since `sharp` is installed automatically for you.
...@@ -17,3 +38,4 @@ You are seeing this error because Image Optimization in production mode (`next s ...@@ -17,3 +38,4 @@ You are seeing this error because Image Optimization in production mode (`next s
- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization) - [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image) - [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)
- [Output File Tracing](/docs/advanced-features/output-file-tracing)
...@@ -547,7 +547,7 @@ export async function imageOptimizer( ...@@ -547,7 +547,7 @@ export async function imageOptimizer(
// TODO: should we ensure squoosh also works even though we don't // TODO: should we ensure squoosh also works even though we don't
// recommend it be used in production and this is a production feature // recommend it be used in production and this is a production feature
console.error( console.error(
`Error: 'sharp' is required to be installed in standalone mode for the image optimization to function correctly` `Error: 'sharp' is required to be installed in standalone mode for the image optimization to function correctly. Read more at: https://nextjs.org/docs/messages/sharp-missing-in-production`
) )
throw new ImageError(500, 'internal server error') throw new ImageError(500, 'internal server error')
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment