diff --git a/.changeset/cyan-carrots-stare.md b/.changeset/cyan-carrots-stare.md new file mode 100644 index 000000000000..f7bcd48707a4 --- /dev/null +++ b/.changeset/cyan-carrots-stare.md @@ -0,0 +1,5 @@ +--- +'astro': patch +--- + +Update error message when Sharp couldn't be found (tends to happen on pnpm notably) diff --git a/packages/astro/config.d.ts b/packages/astro/config.d.ts index 33aebd4f7a01..cdd38c4ea147 100644 --- a/packages/astro/config.d.ts +++ b/packages/astro/config.d.ts @@ -24,3 +24,10 @@ export function sharpImageService(): ImageServiceConfig; * Return the configuration needed to use the Squoosh-based image service */ export function squooshImageService(): ImageServiceConfig; + +/** + * Return the configuration needed to use the passthrough image service. This image services does not perform + * any image transformations, and is mainly useful when your platform does not support other image services, or you are + * not using Astro's built-in image processing. + */ +export function passthroughImageService(): ImageServiceConfig; diff --git a/packages/astro/config.mjs b/packages/astro/config.mjs index 9f5883015c65..208313287817 100644 --- a/packages/astro/config.mjs +++ b/packages/astro/config.mjs @@ -13,3 +13,10 @@ export function squooshImageService() { config: {}, }; } + +export function passthroughImageService() { + return { + entrypoint: 'astro/assets/services/noop', + config: {}, + }; +} diff --git a/packages/astro/src/assets/services/sharp.ts b/packages/astro/src/assets/services/sharp.ts index 7f70b926891c..0819ffcd13bf 100644 --- a/packages/astro/src/assets/services/sharp.ts +++ b/packages/astro/src/assets/services/sharp.ts @@ -1,4 +1,5 @@ import type { FormatEnum } from 'sharp'; +import { AstroError, AstroErrorData } from '../../core/errors/index.js'; import type { ImageOutputFormat, ImageQualityPreset } from '../types.js'; import { baseService, @@ -21,7 +22,7 @@ async function loadSharp() { try { sharpImport = (await import('sharp')).default; } catch (e) { - throw new Error('Could not find Sharp. Please install Sharp manually into your project.'); + throw new AstroError(AstroErrorData.MissingSharp); } return sharpImport; diff --git a/packages/astro/src/core/errors/errors-data.ts b/packages/astro/src/core/errors/errors-data.ts index 9bac015190f5..58ec0d4be982 100644 --- a/packages/astro/src/core/errors/errors-data.ts +++ b/packages/astro/src/core/errors/errors-data.ts @@ -791,6 +791,32 @@ export const InvalidDynamicRoute = { message: (route: string, invalidParam: string, received: string) => `The ${invalidParam} param for route ${route} is invalid. Received **${received}**.`, } satisfies ErrorData; +/** + * @docs + * @see + * - [Default Image Service](https://docs.astro.build/en/guides/images/#default-image-service) + * - [Image Component](https://docs.astro.build/en/guides/images/#image--astroassets) + * - [Image Services API](https://docs.astro.build/en/reference/image-service-reference/) + * @description + * Sharp is the default image service used for `astro:assets`. When using a [strict package manager](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) like pnpm, Sharp must be installed manually into your project in order to use image processing. + * + * If you are not using `astro:assets` for image processing, and do not wish to install Sharp, you can configure the following passthrough image service that does no processing: + * + * ```js + * import { defineConfig, passthroughImageService } from "astro/config"; + * export default defineConfig({ + * image: { + * service: passthroughImageService(), + * }, + * }); + * ``` + */ +export const MissingSharp = { + name: 'MissingSharp', + title: 'Could not find Sharp.', + message: 'Could not find Sharp. Please install Sharp (`sharp`) manually into your project.', + hint: "See Sharp's installation instructions for more information: https://sharp.pixelplumbing.com/install. If you are not relying on `astro:assets` to optimize, transform, or process any images, you can configure a passthrough image service instead of installing Sharp. See https://docs.astro.build/en/reference/errors/missing-sharp for more information.", +}; // No headings here, that way Vite errors are merged with Astro ones in the docs, which makes more sense to users. // Vite Errors - 4xxx /**