add error hints (#3350)

* add error hints

* chore: add changeset

Co-authored-by: Nate Moore <nate@skypack.dev>

3 files changed, 19 insertions, 0 deletions

diff --git a/.changeset/dry-glasses-guess.md b/.changeset/dry-glasses-guess.md
new file mode 100644
index 000000000..81b4ac2e6
--- /dev/null
+++ b/.changeset/dry-glasses-guess.md
@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Improve error hints for packages that should be added to `vite.ssr.noExternal`
diff --git a/packages/astro/src/core/errors.ts b/packages/astro/src/core/errors.ts
index 0150978dc..2b1be3a3a 100644
--- a/packages/astro/src/core/errors.ts
+++ b/packages/astro/src/core/errors.ts
@@ -9,6 +9,7 @@ export interface ErrorWithMetadata {
 	[name: string]: any;
 	message: string;
 	stack: string;
+	hint?: string;
 	id?: string;
 	frame?: string;
 	plugin?: string;
@@ -40,6 +41,13 @@ export function fixViteErrorMessage(_err: unknown, server: ViteDevServer) {
 	return err;
 }
 
+function generateHint(err: ErrorWithMetadata): string | undefined {
+	if (/Unknown file extension \"\.(jsx|vue|svelte|astro)\" for /.test(err.message)) {
+		return 'You likely need to add this package to `vite.ssr.noExternal` in your astro config file.';
+	}
+	return undefined;
+}
+
 /**
  * Takes any error-like object and returns a standardized Error + metadata object.
  * Useful for consistent reporting regardless of where the error surfaced from.
@@ -70,9 +78,11 @@ export function collectErrorMetadata(e: any): ErrorWithMetadata {
 		if (pluginName) {
 			err.plugin = pluginName;
 		}
+		err.hint = generateHint(err);
 		return err;
 	}
 
 	// Generic error (probably from Vite, and already formatted)
+		e.hint = generateHint(e);
 	return e;
 }
diff --git a/packages/astro/src/core/messages.ts b/packages/astro/src/core/messages.ts
index 38f9d78f5..e96dd4bb1 100644
--- a/packages/astro/src/core/messages.ts
+++ b/packages/astro/src/core/messages.ts
@@ -212,6 +212,10 @@ export function formatConfigErrorMessage(err: ZodError) {
 export function formatErrorMessage(_err: Error, args: string[] = []): string {
 	const err = collectErrorMetadata(_err);
 	args.push(`${bgRed(black(` error `))}${red(bold(padMultilineString(err.message)))}`);
+	if (err.hint) {
+		args.push(`  ${bold('Hint:')}`);
+    	args.push(yellow(padMultilineString(err.hint, 4)));
+	}
 	if (err.id) {
 		args.push(`  ${bold('File:')}`);
 		args.push(red(`    ${err.id}`));