feat: hybrid output

packages/astro/src/@types/astro.ts

@@ -553,7 +553,7 @@ export interface AstroUserConfig {
 	/**
 	 * @docs
 	 * @name output
-	 * @type {('static' | 'server')}
+	 * @type {('static' | 'server' | 'hybrid')}
 	 * @default `'static'`
 	 * @see adapter
 	 * @description
@@ -562,6 +562,7 @@ export interface AstroUserConfig {
 	 *
 	 * - 'static' - Building a static site to be deploy to any static host.
 	 * - 'server' - Building an app to be deployed to a host supporting SSR (server-side rendering).
+	 * - 'hybrid' - Building a static site with a few server-side rendered pages.
 	 *
 	 * ```js
 	 * import { defineConfig } from 'astro/config';
@@ -571,7 +572,7 @@ export interface AstroUserConfig {
 	 * })
 	 * ```
 	 */
-	output?: 'static' | 'server';
+	output?: 'static' | 'server' | 'hybrid';
 
 	/**
 	 * @docs
@@ -612,14 +613,14 @@ export interface AstroUserConfig {
 		 * @type {string}
 		 * @default `'./dist/client'`
 		 * @description
-		 * Controls the output directory of your client-side CSS and JavaScript when `output: 'server'` only.
+		 * Controls the output directory of your client-side CSS and JavaScript when `output: 'server'` or `output: 'hybrid'` only.
 		 * `outDir` controls where the code is built to.
 		 *
 		 * This value is relative to the `outDir`.
 		 *
 		 * ```js
 		 * {
-		 *   output: 'server',
+		 *   output: 'server', // or 'hybrid'
 		 *   build: {
 		 *     client: './client'
 		 *   }
@@ -1095,6 +1096,44 @@ export interface AstroUserConfig {
 		 * ```
 		 */
 		middleware?: boolean;
+
+		/**
+		 * @docs
+		 * @name experimental.hybridOutput
+		 * @type {boolean}
+		 * @default `false`
+		 * @version 2.5.0
+		 * @description
+		 * Enable experimental support for hybrid SSR with pre-rendering enabled by default.
+		 *
+		 * To enable this feature, first set `experimental.hybridOutput` to `true` in your Astro config, and set `output` to `hybrid`.
+		 *
+		 * ```js
+		 * {
+		 *  output: 'hybrid',
+		 * 	experimental: {
+		 *		hybridOutput: true,
+		 * 	},
+		 * }
+		 * ```
+		 * Then add `export const prerender =  false` to any page or endpoint you want to opt-out of pre-rendering.
+		 * ```astro
+		 * ---
+		 * // pages/contact.astro
+		 * export const prerender = false
+		 *
+		 * if (Astro.request.method === 'POST') {
+		 *  // handle form submission
+		 * }
+		 * ---
+		 * <form method="POST">
+		 * 	<input type="text" name="name" />
+		 * 	<input type="email" name="email" />
+		 * 	<button type="submit">Submit</button>
+		 * </form>
+		 * ```
+		 */
+		hybridOutput?: boolean;
 	};
 
 	// Legacy options to be removed

packages/astro/src/assets/internal.ts

@@ -113,7 +113,11 @@ export async function generateImage(
 	}
 
 	let serverRoot: URL, clientRoot: URL;
-	if (buildOpts.settings.config.output === 'server') {
+	if (
+		buildOpts.settings.config.output === 'server' ||
+		(buildOpts.settings.config.experimental.hybridOutput &&
+			buildOpts.settings.config.output === 'hybrid')
+	) {
 		serverRoot = buildOpts.settings.config.build.server;
 		clientRoot = buildOpts.settings.config.build.client;
 	} else {

packages/astro/src/core/build/generate.ts

@@ -93,7 +93,9 @@ export function chunkIsPage(
 
 export async function generatePages(opts: StaticBuildOptions, internals: BuildInternals) {
 	const timer = performance.now();
-	const ssr = opts.settings.config.output === 'server';
+	const ssr =
+		opts.settings.config.output === 'server' ||
+		(opts.settings.config.experimental.hybridOutput && opts.settings.config.output === 'hybrid'); // hybrid mode is essentially SSR with prerender by default
 	const serverEntry = opts.buildConfig.serverEntry;
 	const outFolder = ssr ? opts.buildConfig.server : getOutDirWithinCwd(opts.settings.config.outDir);
 
@@ -231,7 +233,10 @@ async function getPathsForRoute(
 			route: pageData.route,
 			isValidate: false,
 			logging: opts.logging,
-			ssr: opts.settings.config.output === 'server',
+			ssr:
+				opts.settings.config.output === 'server' ||
+				(opts.settings.config.experimental.hybridOutput &&
+					opts.settings.config.output === 'hybrid'),
 		})
 			.then((_result) => {
 				const label = _result.staticPaths.length === 1 ? 'page' : 'pages';
@@ -407,7 +412,9 @@ async function generatePath(
 		}
 	}
 
-	const ssr = settings.config.output === 'server';
+	const ssr =
+		settings.config.output === 'server' ||
+		(settings.config.experimental.hybridOutput && settings.config.output === 'hybrid');
 	const url = getUrlForPath(
 		pathname,
 		opts.settings.config.base,

packages/astro/src/core/build/index.ts

@@ -1,6 +1,11 @@
 import type { AstroTelemetry } from '@astrojs/telemetry';
-import type { AstroSettings, BuildConfig, ManifestData, RuntimeMode } from '../../@types/astro';
-import type { LogOptions } from '../logger/core';
+import type {
+	AstroConfig,
+	AstroSettings,
+	BuildConfig,
+	ManifestData,
+	RuntimeMode,
+} from '../../@types/astro';
 
 import fs from 'fs';
 import * as colors from 'kleur/colors';
@@ -14,7 +19,7 @@ import {
 	runHookConfigSetup,
 } from '../../integrations/index.js';
 import { createVite } from '../create-vite.js';
-import { debug, info, levels, timerMessage } from '../logger/core.js';
+import { debug, info, levels, timerMessage, warn, type LogOptions } from '../logger/core.js';
 import { printHelp } from '../messages.js';
 import { apply as applyPolyfill } from '../polyfill.js';
 import { RouteCache } from '../render/route-cache.js';
@@ -233,7 +238,7 @@ class AstroBuilder {
 		logging: LogOptions;
 		timeStart: number;
 		pageCount: number;
-		buildMode: 'static' | 'server';
+		buildMode: AstroConfig['output'];
 	}) {
 		const total = getTimeStat(timeStart, performance.now());
 

packages/astro/src/core/build/plugins/plugin-pages.ts

@@ -6,12 +6,12 @@ import { eachPageData, hasPrerenderedPages, type BuildInternals } from '../inter
 import type { AstroBuildPlugin } from '../plugin';
 import type { StaticBuildOptions } from '../types';
 
-export function vitePluginPages(opts: StaticBuildOptions, internals: BuildInternals): VitePlugin {
+function vitePluginPages(opts: StaticBuildOptions, internals: BuildInternals): VitePlugin {
 	return {
 		name: '@astro/plugin-build-pages',
 
 		options(options) {
-			if (opts.settings.config.output === 'static' || hasPrerenderedPages(internals)) {
+			if (opts.settings.config.output === 'static') {
 				return addRollupInput(options, [pagesVirtualModuleId]);
 			}
 		},

packages/astro/src/core/build/plugins/plugin-prerender.ts

@@ -4,10 +4,7 @@ import type { AstroBuildPlugin } from '../plugin.js';
 import type { StaticBuildOptions } from '../types';
 import { extendManualChunks } from './util.js';
 
-export function vitePluginPrerender(
-	opts: StaticBuildOptions,
-	internals: BuildInternals
-): VitePlugin {
+function vitePluginPrerender(opts: StaticBuildOptions, internals: BuildInternals): VitePlugin {
 	return {
 		name: 'astro:rollup-plugin-prerender',
 
@@ -26,6 +23,7 @@ export function vitePluginPrerender(
 							pageInfo.route.prerender = true;
 							return 'prerender';
 						}
+						pageInfo.route.prerender = false;
 						// dynamic pages should all go in their own chunk in the pages/* directory
 						return `pages/all`;
 					}

packages/astro/src/core/build/plugins/plugin-ssr.ts

@@ -1,7 +1,6 @@
 import type { Plugin as VitePlugin } from 'vite';
 import type { AstroAdapter, AstroConfig } from '../../../@types/astro';
 import type { SerializedRouteInfo, SerializedSSRManifest } from '../../app/types';
-import type { BuildInternals } from '../internal.js';
 import type { StaticBuildOptions } from '../types';
 
 import glob from 'fast-glob';
@@ -13,15 +12,15 @@ import { joinPaths, prependForwardSlash } from '../../path.js';
 import { serializeRouteData } from '../../routing/index.js';
 import { addRollupInput } from '../add-rollup-input.js';
 import { getOutFile, getOutFolder } from '../common.js';
-import { cssOrder, eachPageData, mergeInlineCss } from '../internal.js';
+import { cssOrder, eachPageData, mergeInlineCss, type BuildInternals } from '../internal.js';
 import type { AstroBuildPlugin } from '../plugin';
 
 export const virtualModuleId = '@astrojs-ssr-virtual-entry';
 const resolvedVirtualModuleId = '\0' + virtualModuleId;
 const manifestReplace = '@@ASTRO_MANIFEST_REPLACE@@';
 const replaceExp = new RegExp(`['"](${manifestReplace})['"]`, 'g');
 
-export function vitePluginSSR(
+function vitePluginSSR(
 	internals: BuildInternals,
 	adapter: AstroAdapter,
 	config: AstroConfig
@@ -248,7 +247,10 @@ export function pluginSSR(
 	options: StaticBuildOptions,
 	internals: BuildInternals
 ): AstroBuildPlugin {
-	const ssr = options.settings.config.output === 'server';
+	const ssr =
+		options.settings.config.output === 'server' ||
+		(options.settings.config.experimental.hybridOutput &&
+			options.settings.config.output === 'hybrid');
 	return {
 		build: 'ssr',
 		hooks: {

packages/astro/src/core/build/static-build.ts

@@ -111,15 +111,17 @@ export async function viteBuild(opts: StaticBuildOptions) {
 
 export async function staticBuild(opts: StaticBuildOptions, internals: BuildInternals) {
 	const { settings } = opts;
-	switch (settings.config.output) {
-		case 'static': {
+	const isHybridOutput =
+		settings.config.experimental.hybridOutput && settings.config.output === 'hybrid';
+	switch (true) {
+		case settings.config.output === 'static': {
 			settings.timer.start('Static generate');
 			await generatePages(opts, internals);
 			await cleanServerOutput(opts);
 			settings.timer.end('Static generate');
 			return;
 		}
-		case 'server': {
+		case settings.config.output === 'server' || isHybridOutput: {
 			settings.timer.start('Server generate');
 			await generatePages(opts, internals);
 			await cleanStaticOutput(opts, internals);
@@ -138,7 +140,9 @@ async function ssrBuild(
 	container: AstroBuildPluginContainer
 ) {
 	const { settings, viteConfig } = opts;
-	const ssr = settings.config.output === 'server';
+	const ssr =
+		settings.config.output === 'server' ||
+		(settings.config.experimental.hybridOutput && settings.config.output === 'hybrid');
 	const out = ssr ? opts.buildConfig.server : getOutDirWithinCwd(settings.config.outDir);
 
 	const { lastVitePlugins, vitePlugins } = container.runBeforeHook('ssr', input);
@@ -207,7 +211,9 @@ async function clientBuild(
 ) {
 	const { settings, viteConfig } = opts;
 	const timer = performance.now();
-	const ssr = settings.config.output === 'server';
+	const ssr =
+		settings.config.output === 'server' ||
+		(settings.config.experimental.hybridOutput && settings.config.output === 'hybrid');
 	const out = ssr ? opts.buildConfig.client : getOutDirWithinCwd(settings.config.outDir);
 
 	// Nothing to do if there is no client-side JS.
@@ -273,7 +279,7 @@ async function runPostBuildHooks(
 	const buildConfig = container.options.settings.config.build;
 	for (const [fileName, mutation] of mutations) {
 		const root =
-			config.output === 'server'
+			config.output === 'server' || (config.experimental.hybridOutput && config.output === 'hybrid')
 				? mutation.build === 'server'
 					? buildConfig.server
 					: buildConfig.client
@@ -294,7 +300,9 @@ async function cleanStaticOutput(opts: StaticBuildOptions, internals: BuildInter
 		if (pageData.route.prerender)
 			allStaticFiles.add(internals.pageToBundleMap.get(pageData.moduleSpecifier));
 	}
-	const ssr = opts.settings.config.output === 'server';
+	const ssr =
+		opts.settings.config.output === 'server' ||
+		(opts.settings.config.experimental.hybridOutput && opts.settings.config.output === 'hybrid');
 	const out = ssr ? opts.buildConfig.server : getOutDirWithinCwd(opts.settings.config.outDir);
 	// The SSR output is all .mjs files, the client output is not.
 	const files = await glob('**/*.mjs', {

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

@@ -223,6 +223,12 @@ export async function openConfig(configOptions: LoadConfigOptions): Promise<Open
 	}
 	const astroConfig = await resolveConfig(userConfig, root, flags, configOptions.cmd);
 
+	if (isHybridMalconfigured(astroConfig)) {
+		throw new Error(
+			`The "output" config option must be set to "hybrid" and "experimental.hybridOutput" must be set to true to use the hybrid output mode. Falling back to "static" output mode.`
+		);
+	}
+
 	return {
 		astroConfig,
 		userConfig,
@@ -351,3 +357,9 @@ export function mergeConfig(
 ): Record<string, any> {
 	return mergeConfigRecursively(defaults, overrides, isRoot ? '' : '.');
 }
+
+// TODO: remove after the experimetal phase when
+// it won't be needed to edit two config fields to enable the feature
+function isHybridMalconfigured(config: AstroConfig) {
+	return config.experimental.hybridOutput ? config.output !== 'hybrid' : config.output === 'hybrid';
+}

packages/astro/src/core/config/schema.ts

@@ -38,6 +38,7 @@ const ASTRO_CONFIG_DEFAULTS: AstroUserConfig & any = {
 	legacy: {},
 	experimental: {
 		assets: false,
+		hybridOutput: false,
 		inlineStylesheets: 'never',
 		middleware: false,
 	},
@@ -76,7 +77,7 @@ 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'),
 	scopedStyleStrategy: z
@@ -200,6 +201,7 @@ export const AstroConfigSchema = z.object({
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.inlineStylesheets),
 			middleware: z.oboolean().optional().default(ASTRO_CONFIG_DEFAULTS.experimental.middleware),
+			hybridOutput: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.experimental.hybridOutput),
 		})
 		.optional()
 		.default({}),

packages/astro/src/core/config/settings.ts

@@ -16,7 +16,9 @@ export function createBaseSettings(config: AstroConfig): AstroSettings {
 
 		adapter: undefined,
 		injectedRoutes:
-			config.experimental.assets && config.output === 'server'
+			config.experimental.assets &&
+			(config.output === 'server' ||
+				(config.experimental.hybridOutput && config.output === 'hybrid'))
 				? [{ pattern: '/_image', entryPoint: 'astro/assets/image-endpoint' }]
 				: [],
 		pageExtensions: ['.astro', '.html', ...SUPPORTED_MARKDOWN_FILE_EXTENSIONS],

packages/astro/src/core/endpoint/index.ts

@@ -169,7 +169,12 @@ function isRedirect(statusCode: number) {
 }
 
 export function throwIfRedirectNotAllowed(response: Response, config: AstroConfig) {
-	if (config.output !== 'server' && isRedirect(response.status)) {
+	if (
+		config.output !== 'server' &&
+		!config.experimental.hybridOutput &&
+		config.output !== 'hybrid' &&
+		isRedirect(response.status)
+	) {
 		throw new AstroError(AstroErrorData.StaticRedirectNotAvailable);
 	}
 }