From faf838766a5dbc8bb0c5b54127e7e714273b453a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Mon, 3 Oct 2022 18:12:03 +0200 Subject: [PATCH 1/7] docs: improve error when `sharp` is missing in standalone mode --- docs/advanced-features/output-file-tracing.md | 22 +++++++++++++--- errors/manifest.json | 4 +++ errors/missing-sharp-standalone.md | 26 +++++++++++++++++++ packages/next/server/image-optimizer.ts | 2 +- 4 files changed, 49 insertions(+), 5 deletions(-) create mode 100644 errors/missing-sharp-standalone.md diff --git a/docs/advanced-features/output-file-tracing.md b/docs/advanced-features/output-file-tracing.md index 69dcfa1568f83..90ad2f5347810 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 relies on [Image Optimization](/docs/basic-features/image-optimization), make sure to also install `sharp` as a dependency for image optimization to function correctly in standalone mode, using one of the following commands: + +```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/manifest.json b/errors/manifest.json index 41bb35c7d6004..f61b3b8644b22 100644 --- a/errors/manifest.json +++ b/errors/manifest.json @@ -737,6 +737,10 @@ { "title": "nonce-contained-invalid-characters", "path": "/errors/nonce-contained-invalid-characters.md" + }, + { + "title": "missing-sharp-standalone", + "path": "/errors/missing-sharp-standalone.md" } ] } diff --git a/errors/missing-sharp-standalone.md b/errors/missing-sharp-standalone.md new file mode 100644 index 0000000000000..851033f233247 --- /dev/null +++ b/errors/missing-sharp-standalone.md @@ -0,0 +1,26 @@ +# Missing sharp in standalone mode + +#### Why This Error Occurred + +You have enabled `output: "standalone"`, but forgot to install `sharp` as a dependency while depending on it due to [Image Optimization](https://nextjs.org/docs/basic-features/image-optimization). For the image optimization to function correctly, `sharp` needs to be installed. + +#### Possible Ways to Fix It + +Install `sharp` as a dependency before running `next build`: + +```bash +npm i sharp +``` + +```bash +yarn add sharp +``` + +```bash +pnpm add sharp +``` + +### Useful Links + +- [Output File Tracing](/docs/advanced-features/output-file-tracing) +- [Image Optimization](/docs/basic-features/image-optimization) diff --git a/packages/next/server/image-optimizer.ts b/packages/next/server/image-optimizer.ts index ea89c37615a6d..d7e1f843bf0ee 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/missing-sharp-standalone` ) throw new ImageError(500, 'internal server error') } From f4382a9c24135cf3e5269ae89bc9dd5570005bfa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Mon, 3 Oct 2022 18:15:34 +0200 Subject: [PATCH 2/7] rename --- errors/manifest.json | 4 ++-- ...ing-sharp-standalone.md => sharp-missing-in-standalone.md} | 0 packages/next/server/image-optimizer.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename errors/{missing-sharp-standalone.md => sharp-missing-in-standalone.md} (100%) diff --git a/errors/manifest.json b/errors/manifest.json index f61b3b8644b22..7653addd0f686 100644 --- a/errors/manifest.json +++ b/errors/manifest.json @@ -739,8 +739,8 @@ "path": "/errors/nonce-contained-invalid-characters.md" }, { - "title": "missing-sharp-standalone", - "path": "/errors/missing-sharp-standalone.md" + "title": "sharp-missing-in-standalone", + "path": "/errors/sharp-missing-in-standalone.md" } ] } diff --git a/errors/missing-sharp-standalone.md b/errors/sharp-missing-in-standalone.md similarity index 100% rename from errors/missing-sharp-standalone.md rename to errors/sharp-missing-in-standalone.md diff --git a/packages/next/server/image-optimizer.ts b/packages/next/server/image-optimizer.ts index d7e1f843bf0ee..9ca17f12f3796 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. Read more at: https://nextjs.org/docs/messages/missing-sharp-standalone` + `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-standalone` ) throw new ImageError(500, 'internal server error') } From 6b7853d0bea6cc9215f1b3d3cad641fd1189cbb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Mon, 3 Oct 2022 18:16:54 +0200 Subject: [PATCH 3/7] add link to `next/image` --- errors/sharp-missing-in-standalone.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/errors/sharp-missing-in-standalone.md b/errors/sharp-missing-in-standalone.md index 851033f233247..8a7d9ba215ecb 100644 --- a/errors/sharp-missing-in-standalone.md +++ b/errors/sharp-missing-in-standalone.md @@ -23,4 +23,5 @@ pnpm add sharp ### Useful Links - [Output File Tracing](/docs/advanced-features/output-file-tracing) -- [Image Optimization](/docs/basic-features/image-optimization) +- [Image Optimization Documentation](/docs/basic-features/image-optimization) +- [`next/image` Documentation](/docs/api-reference/next/image) From e0e25a295e2ed6686fc7228663f3951bcda8b84a Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Mon, 3 Oct 2022 11:19:31 -0700 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Steven --- docs/advanced-features/output-file-tracing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/output-file-tracing.md b/docs/advanced-features/output-file-tracing.md index 90ad2f5347810..b12c8a8c757eb 100644 --- a/docs/advanced-features/output-file-tracing.md +++ b/docs/advanced-features/output-file-tracing.md @@ -36,7 +36,7 @@ Additionally, a minimal `server.js` file is also output which can be used instea 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 relies on [Image Optimization](/docs/basic-features/image-optimization), make sure to also install `sharp` as a dependency for image optimization to function correctly in standalone mode, using one of the following commands: +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 From 6f2a871072bf9d9aeabefb1188174e452f0742b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Tue, 4 Oct 2022 17:06:17 +0200 Subject: [PATCH 5/7] address review comments --- errors/manifest.json | 4 ---- errors/sharp-missing-in-production.md | 26 ++++++++++++++++++++++-- errors/sharp-missing-in-standalone.md | 27 ------------------------- packages/next/server/image-optimizer.ts | 2 +- 4 files changed, 25 insertions(+), 34 deletions(-) delete mode 100644 errors/sharp-missing-in-standalone.md diff --git a/errors/manifest.json b/errors/manifest.json index 7653addd0f686..41bb35c7d6004 100644 --- a/errors/manifest.json +++ b/errors/manifest.json @@ -737,10 +737,6 @@ { "title": "nonce-contained-invalid-characters", "path": "/errors/nonce-contained-invalid-characters.md" - }, - { - "title": "sharp-missing-in-standalone", - "path": "/errors/sharp-missing-in-standalone.md" } ] } diff --git a/errors/sharp-missing-in-production.md b/errors/sharp-missing-in-production.md index 96903efad9ca5..a38381238315c 100644 --- a/errors/sharp-missing-in-production.md +++ b/errors/sharp-missing-in-production.md @@ -2,13 +2,34 @@ #### 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 +- 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, reboot the server by running `next start` again, or if you have `output: "standalone"` enabled, rebuild your project with `next build` and reboot the server with `node server.js`. + - 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` > 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/errors/sharp-missing-in-standalone.md b/errors/sharp-missing-in-standalone.md deleted file mode 100644 index 8a7d9ba215ecb..0000000000000 --- a/errors/sharp-missing-in-standalone.md +++ /dev/null @@ -1,27 +0,0 @@ -# Missing sharp in standalone mode - -#### Why This Error Occurred - -You have enabled `output: "standalone"`, but forgot to install `sharp` as a dependency while depending on it due to [Image Optimization](https://nextjs.org/docs/basic-features/image-optimization). For the image optimization to function correctly, `sharp` needs to be installed. - -#### Possible Ways to Fix It - -Install `sharp` as a dependency before running `next build`: - -```bash -npm i sharp -``` - -```bash -yarn add sharp -``` - -```bash -pnpm add sharp -``` - -### Useful Links - -- [Output File Tracing](/docs/advanced-features/output-file-tracing) -- [Image Optimization Documentation](/docs/basic-features/image-optimization) -- [`next/image` Documentation](/docs/api-reference/next/image) diff --git a/packages/next/server/image-optimizer.ts b/packages/next/server/image-optimizer.ts index 9ca17f12f3796..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. Read more at: https://nextjs.org/docs/messages/sharp-missing-in-standalone` + `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') } From 7cb890c396ff8910d3f4114e1de9cb05345db6a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Wed, 5 Oct 2022 16:35:18 +0200 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Steven --- errors/sharp-missing-in-production.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/errors/sharp-missing-in-production.md b/errors/sharp-missing-in-production.md index a38381238315c..0a147d6f1b96f 100644 --- a/errors/sharp-missing-in-production.md +++ b/errors/sharp-missing-in-production.md @@ -28,7 +28,7 @@ yarn add sharp pnpm add sharp ``` -Then, reboot the server by running `next start` again, or if you have `output: "standalone"` enabled, rebuild your project with `next build` and reboot the server with `node server.js`. +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 `NEXT_SHARP_PATH=/tmp/node_modules/sharp next start` From 44f97fdd9e83949bdadecdc0d9bb68e1731d27f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Wed, 5 Oct 2022 16:37:47 +0200 Subject: [PATCH 7/7] Update sharp-missing-in-production.md --- errors/sharp-missing-in-production.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/errors/sharp-missing-in-production.md b/errors/sharp-missing-in-production.md index 0a147d6f1b96f..d7c70fde8169a 100644 --- a/errors/sharp-missing-in-production.md +++ b/errors/sharp-missing-in-production.md @@ -30,7 +30,7 @@ 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 `NEXT_SHARP_PATH=/tmp/node_modules/sharp next start` +- 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.