diff --git a/docs/advanced-features/output-file-tracing.md b/docs/advanced-features/output-file-tracing.md index 69dcfa1568f83..b12c8a8c757eb 100644 --- a/docs/advanced-features/output-file-tracing.md +++ b/docs/advanced-features/output-file-tracing.md @@ -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. -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 -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`: @@ -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. 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 - 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 = { } ``` -- 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. diff --git a/errors/sharp-missing-in-production.md b/errors/sharp-missing-in-production.md index 96903efad9ca5..d7c70fde8169a 100644 --- a/errors/sharp-missing-in-production.md +++ b/errors/sharp-missing-in-production.md @@ -2,14 +2,35 @@ #### 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. +- 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 -- Install `sharp` by running `yarn add sharp` in your project directory and then reboot the server by running `next start` again -- 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` +- Install `sharp` by running one of the following commands in your project directory: + +```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. @@ -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) - [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image) +- [Output File Tracing](/docs/advanced-features/output-file-tracing) diff --git a/packages/next/server/image-optimizer.ts b/packages/next/server/image-optimizer.ts index ea89c37615a6d..d0518eb7ab983 100644 --- a/packages/next/server/image-optimizer.ts +++ b/packages/next/server/image-optimizer.ts @@ -547,7 +547,7 @@ export async function imageOptimizer( // TODO: should we ensure squoosh also works even though we don't // recommend it be used in production and this is a production feature 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') }