fix: better error when Sharp can't be resolved (ex: pnpm) (#8128)

* fix: better error when Sharp can't be resolved (ex: pnpm)

* chore: changeset

* Apply suggestions from code review

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

---------

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

5 files changed, 47 insertions, 1 deletions

diff --git a/.changeset/cyan-carrots-stare.md b/.changeset/cyan-carrots-stare.md
new file mode 100644
index 000000000..f7bcd4870
--- /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 33aebd4f7..cdd38c4ea 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 9f5883015..208313287 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 7f70b9268..0819ffcd1 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 9bac01519..58ec0d4be 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
 /**