feat: print a more helpful error message for output: hybrid (#14958)

* feat: print a more helpful error message for `output: hybrid`

* Add type predicate

.changeset/long-comics-invite.md

@@ -0,0 +1,7 @@
+---
+'astro': minor
+---
+
+Gives a helpful error message if a user sets `output: "hybrid"` in their Astro config. 
+
+The option was removed in Astro 5, but lots of content online still references it, and LLMs often suggest it. It's not always clear that the replacement is `output: "static"`, rather than `output: "server"`. This change adds a helpful error message to guide humans and robots.

packages/astro/src/core/config/schemas/base.ts

@@ -149,9 +149,13 @@ export const AstroConfigSchema = z.object({
 		.optional()
 		.default(ASTRO_CONFIG_DEFAULTS.trailingSlash),
 	output: z
-		.union([z.literal('static'), z.literal('server')])
+		.union([z.literal('static'), z.literal('server'), z.literal('hybrid')])
 		.optional()
-		.default('static'),
+		.default('static')
+		.refine((val): val is 'static' | 'server' => val !== 'hybrid', {
+			message:
+				'The `output: "hybrid"` option has been removed. Use `output: "static"` (the default) instead, which now behaves the same way.',
+		}),
 	scopedStyleStrategy: z
 		.union([z.literal('where'), z.literal('class'), z.literal('attribute')])
 		.optional()

packages/astro/test/units/config/config-validate.test.js

@@ -90,6 +90,15 @@ describe('Config Validation', () => {
 		);
 	});
 
+	it('errors with helpful message when output is "hybrid"', async () => {
+		const configError = await validateConfig({ output: 'hybrid' }).catch((err) => err);
+		assert.equal(configError instanceof z.ZodError, true);
+		assert.ok(
+			configError.errors[0].message.includes('removed'),
+			'Error message should explain that "hybrid" has been removed',
+		);
+	});
+
 	describe('i18n', async () => {
 		it('defaultLocale is not in locales', async () => {
 			const configError = await validateConfig({