Support custom mode (#12150)

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

.changeset/sixty-coins-worry.md

@@ -0,0 +1,31 @@
+---
+'astro': minor
+---
+
+Adds support for passing values other than `"production"` or `"development"` to the `--mode` flag (e.g. `"staging"`, `"testing"`, or any custom value) to change the value of `import.meta.env.MODE` or the loaded `.env` file. This allows you take advantage of Vite's [mode](https://vite.dev/guide/env-and-mode#modes) feature.
+
+Also adds a new `--devOutput` flag for `astro build` that will output a development-based build.
+
+Note that changing the `mode` does not change the kind of code transform handled by Vite and Astro:
+
+- In `astro dev`, Astro will transform code with debug information.
+- In `astro build`, Astro will transform code with the most optimized output and removes debug information.
+- In `astro build --devOutput` (new flag), Astro will transform code with debug information like in `astro dev`. 
+
+This enables various usecases like:
+
+```bash
+# Run the dev server connected to a "staging" API
+astro dev --mode staging
+
+# Build a site that connects to a "staging" API
+astro build --mode staging
+
+# Build a site that connects to a "production" API with additional debug information
+astro build --devOutput
+
+# Build a site that connects to a "testing" API
+astro build --mode testing
+```
+
+The different modes can be used to load different `.env` files, e.g. `.env.staging` or `.env.production`, which can be customized for each environment, for example with different `API_URL` environment variable values.

packages/astro/CHANGELOG.md

@@ -1,6 +1,5 @@
 # astro
 
-
 ## 5.0.0-beta.5
 
 ### Minor Changes
@@ -988,7 +987,6 @@
 
   If you are using this service, and cannot migrate to the base Sharp image service, a third-party extraction of the previous service is available here: https://github.com/Princesseuh/astro-image-service-squoosh
 
-
 ## 5.0.0-alpha.0
 
 ### Major Changes
@@ -1064,7 +1062,6 @@
 - Updated dependencies [[`83a2a64`](https://github.com/withastro/astro/commit/83a2a648418ad30f4eb781d1c1b5f2d8a8ac846e)]:
   - @astrojs/markdown-remark@6.0.0-alpha.0
 
-
 ## 4.16.6
 
 ### Patch Changes

packages/astro/src/assets/internal.ts

@@ -1,3 +1,4 @@
+import { isRemotePath } from '@astrojs/internal-helpers/path';
 import { AstroError, AstroErrorData } from '../core/errors/index.js';
 import type { AstroConfig } from '../types/public/config.js';
 import { DEFAULT_HASH_PROPS } from './consts.js';
@@ -11,7 +12,6 @@ import {
 } from './types.js';
 import { isESMImportedImage, isRemoteImage, resolveSrc } from './utils/imageKind.js';
 import { inferRemoteSize } from './utils/remoteProbe.js';
-import {isRemotePath} from "@astrojs/internal-helpers/path";
 
 export async function getConfiguredImageService(): Promise<ImageService> {
 	if (!globalThis?.astroAsset?.imageService) {

packages/astro/src/assets/vite-plugin-assets.ts

@@ -10,7 +10,7 @@ import {
 	removeBase,
 	removeQueryString,
 } from '../core/path.js';
-import type { AstroPluginOptions, AstroSettings } from '../types/astro.js';
+import type { AstroSettings } from '../types/astro.js';
 import { VALID_INPUT_FORMATS, VIRTUAL_MODULE_ID, VIRTUAL_SERVICE_ID } from './consts.js';
 import type { ImageTransform } from './types.js';
 import { getAssetsPrefix } from './utils/getAssetsPrefix.js';
@@ -89,12 +89,10 @@ const addStaticImageFactory = (
 	};
 };
 
-export default function assets({
-	settings,
-	mode,
-}: AstroPluginOptions & { mode: string }): vite.Plugin[] {
+export default function assets({ settings }: { settings: AstroSettings }): vite.Plugin[] {
 	let resolvedConfig: vite.ResolvedConfig;
 	let shouldEmitFile = false;
+	let isBuild = false;
 
 	globalThis.astroAsset = {
 		referencedImages: new Set(),
@@ -104,6 +102,9 @@ export default function assets({
 		// Expose the components and different utilities from `astro:assets`
 		{
 			name: 'astro:assets',
+			config(_, env) {
+				isBuild = env.command === 'build';
+			},
 			async resolveId(id) {
 				if (id === VIRTUAL_SERVICE_ID) {
 					return await this.resolve(settings.config.image.service.entrypoint);
@@ -143,10 +144,7 @@ export default function assets({
 				}
 			},
 			buildStart() {
-				if (mode != 'build') {
-					return;
-				}
-
+				if (!isBuild) return;
 				globalThis.astroAsset.addStaticImage = addStaticImageFactory(settings);
 			},
 			// In build, rewrite paths to ESM imported images in code to their final location

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

@@ -14,6 +14,11 @@ export async function build({ flags }: BuildOptions) {
 			tables: {
 				Flags: [
 					['--outDir <directory>', `Specify the output directory for the build.`],
+					['--mode', `Specify the mode of the project. Defaults to "production".`],
+					[
+						'--devOutput',
+						'Output a development-based build similar to code transformed in `astro dev`.',
+					],
 					[
 						'--force',
 						'Clear the content layer and content collection cache, forcing a full rebuild.',
@@ -28,5 +33,5 @@ export async function build({ flags }: BuildOptions) {
 
 	const inlineConfig = flagsToAstroInlineConfig(flags);
 
-	await _build(inlineConfig);
+	await _build(inlineConfig, { devOutput: !!flags.devOutput });
 }

packages/astro/src/cli/dev/index.ts

@@ -14,6 +14,7 @@ export async function dev({ flags }: DevOptions) {
 			usage: '[...flags]',
 			tables: {
 				Flags: [
+					['--mode', `Specify the mode of the project. Defaults to "development".`],
 					['--port', `Specify which port to run on. Defaults to 4321.`],
 					['--host', `Listen on all addresses, including LAN and public addresses.`],
 					['--host <custom-address>', `Expose on a network IP address at <custom-address>`],

packages/astro/src/cli/flags.ts

@@ -10,7 +10,7 @@ export function flagsToAstroInlineConfig(flags: Flags): AstroInlineConfig {
 	return {
 		// Inline-only configs
 		configFile: typeof flags.config === 'string' ? flags.config : undefined,
-		mode: typeof flags.mode === 'string' ? (flags.mode as AstroInlineConfig['mode']) : undefined,
+		mode: typeof flags.mode === 'string' ? flags.mode : undefined,
 		logLevel: flags.verbose ? 'debug' : flags.silent ? 'silent' : undefined,
 		force: flags.force ? true : undefined,
 

packages/astro/src/config/index.ts

@@ -1,4 +1,4 @@
-import type { UserConfig as ViteUserConfig } from 'vite';
+import type { UserConfig as ViteUserConfig, UserConfigFn as ViteUserConfigFn } from 'vite';
 import { Logger } from '../core/logger/core.js';
 import { createRouteManifest } from '../core/routing/index.js';
 import type { AstroInlineConfig, AstroUserConfig } from '../types/public/config.js';
@@ -11,11 +11,11 @@ export function defineConfig(config: AstroUserConfig) {
 export function getViteConfig(
 	userViteConfig: ViteUserConfig,
 	inlineAstroConfig: AstroInlineConfig = {},
-) {
+): ViteUserConfigFn {
 	// Return an async Vite config getter which exposes a resolved `mode` and `command`
-	return async ({ mode, command }: { mode: 'dev'; command: 'serve' | 'build' }) => {
+	return async ({ mode, command }) => {
 		// Vite `command` is `serve | build`, but Astro uses `dev | build`
-		const cmd = command === 'serve' ? 'dev' : command;
+		const cmd = command === 'serve' ? 'dev' : 'build';
 
 		// Use dynamic import to avoid pulling in deps unless used
 		const [
@@ -46,13 +46,12 @@ export function getViteConfig(
 		const devSSRManifest = createDevelopmentManifest(settings);
 		const viteConfig = await createVite(
 			{
-				mode,
 				plugins: [
 					// Initialize the content listener
 					astroContentListenPlugin({ settings, logger, fs }),
 				],
 			},
-			{ settings, logger, mode, sync: false, manifest, ssrManifest: devSSRManifest },
+			{ settings, command: cmd, logger, mode, sync: false, manifest, ssrManifest: devSSRManifest },
 		);
 		await runHookConfigDone({ settings, logger });
 		return mergeConfig(viteConfig, userViteConfig);

packages/astro/src/content/vite-plugin-content-assets.ts

@@ -21,10 +21,8 @@ import {
 import { hasContentFlag } from './utils.js';
 
 export function astroContentAssetPropagationPlugin({
-	mode,
 	settings,
 }: {
-	mode: string;
 	settings: AstroSettings;
 }): Plugin {
 	let devModuleLoader: ModuleLoader;
@@ -67,9 +65,7 @@ export function astroContentAssetPropagationPlugin({
 			}
 		},
 		configureServer(server) {
-			if (mode === 'dev') {
-				devModuleLoader = createViteLoader(server);
-			}
+			devModuleLoader = createViteLoader(server);
 		},
 		async transform(_, id, options) {
 			if (hasContentFlag(id, PROPAGATED_ASSET_FLAG)) {

packages/astro/src/content/vite-plugin-content-virtual-mod.ts

@@ -56,7 +56,7 @@ export function astroContentVirtualModPlugin({
 		name: 'astro-content-virtual-mod-plugin',
 		enforce: 'pre',
 		configResolved(config) {
-			IS_DEV = config.mode === 'development';
+			IS_DEV = !config.isProduction;
 			dataStoreFile = getDataStoreFile(settings, IS_DEV);
 		},
 		async resolveId(id) {

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

@@ -114,7 +114,7 @@ export class App {
 		return AppPipeline.create(manifestData, {
 			logger: this.#logger,
 			manifest: this.#manifest,
-			mode: 'production',
+			runtimeMode: 'production',
 			renderers: this.#manifest.renderers,
 			defaultRoutes: createDefaultRoutes(this.#manifest),
 			resolve: async (specifier: string) => {

packages/astro/src/core/app/pipeline.ts

@@ -15,7 +15,7 @@ export class AppPipeline extends Pipeline {
 		{
 			logger,
 			manifest,
-			mode,
+			runtimeMode,
 			renderers,
 			resolve,
 			serverLike,
@@ -25,7 +25,7 @@ export class AppPipeline extends Pipeline {
 			AppPipeline,
 			| 'logger'
 			| 'manifest'
-			| 'mode'
+			| 'runtimeMode'
 			| 'renderers'
 			| 'resolve'
 			| 'serverLike'
@@ -36,7 +36,7 @@ export class AppPipeline extends Pipeline {
 		const pipeline = new AppPipeline(
 			logger,
 			manifest,
-			mode,
+			runtimeMode,
 			renderers,
 			resolve,
 			serverLike,

packages/astro/src/core/base-pipeline.ts

@@ -32,9 +32,9 @@ export abstract class Pipeline {
 		readonly logger: Logger,
 		readonly manifest: SSRManifest,
 		/**
-		 * "development" or "production"
+		 * "development" or "production" only
 		 */
-		readonly mode: RuntimeMode,
+		readonly runtimeMode: RuntimeMode,
 		readonly renderers: SSRLoadedRenderer[],
 		readonly resolve: (s: string) => Promise<string>,
 		/**
@@ -51,7 +51,7 @@ export abstract class Pipeline {
 		readonly compressHTML = manifest.compressHTML,
 		readonly i18n = manifest.i18n,
 		readonly middleware = manifest.middleware,
-		readonly routeCache = new RouteCache(logger, mode),
+		readonly routeCache = new RouteCache(logger, runtimeMode),
 		/**
 		 * Used for `Astro.site`.
 		 */

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

@@ -31,7 +31,15 @@ import { collectPagesData } from './page-data.js';
 import { staticBuild, viteBuild } from './static-build.js';
 import type { StaticBuildOptions } from './types.js';
 import { getTimeStat } from './util.js';
+
 export interface BuildOptions {
+	/**
+	 * Output a development-based build similar to code transformed in `astro dev`. This
+	 * can be useful to test build-only issues with additional debugging information included.
+	 *
+	 * @default false
+	 */
+	devOutput?: boolean;
 	/**
 	 * Teardown the compiler WASM instance after build. This can improve performance when
 	 * building once, but may cause a performance hit if building multiple times in a row.
@@ -52,7 +60,7 @@ export default async function build(
 	inlineConfig: AstroInlineConfig,
 	options: BuildOptions = {},
 ): Promise<void> {
-	ensureProcessNodeEnv('production');
+	ensureProcessNodeEnv(options.devOutput ? 'development' : 'production');
 	applyPolyfill();
 	const logger = createNodeLogger(inlineConfig);
 	const { userConfig, astroConfig } = await resolveConfig(inlineConfig, 'build');
@@ -67,29 +75,31 @@ export default async function build(
 	const builder = new AstroBuilder(settings, {
 		...options,
 		logger,
-		mode: inlineConfig.mode,
+		mode: inlineConfig.mode ?? 'production',
+		runtimeMode: options.devOutput ? 'development' : 'production',
 	});
 	await builder.run();
 }
 
 interface AstroBuilderOptions extends BuildOptions {
 	logger: Logger;
-	mode?: RuntimeMode;
+	mode: string;
+	runtimeMode: RuntimeMode;
 }
 
 class AstroBuilder {
 	private settings: AstroSettings;
 	private logger: Logger;
-	private mode: RuntimeMode = 'production';
+	private mode: string;
+	private runtimeMode: RuntimeMode;
 	private origin: string;
 	private manifest: ManifestData;
 	private timer: Record<string, number>;
 	private teardownCompiler: boolean;
 
 	constructor(settings: AstroSettings, options: AstroBuilderOptions) {
-		if (options.mode) {
-			this.mode = options.mode;
-		}
+		this.mode = options.mode;
+		this.runtimeMode = options.runtimeMode;
 		this.settings = settings;
 		this.logger = options.logger;
 		this.teardownCompiler = options.teardownCompiler ?? true;
@@ -127,7 +137,6 @@ class AstroBuilder {
 
 		const viteConfig = await createVite(
 			{
-				mode: this.mode,
 				server: {
 					hmr: false,
 					middlewareMode: true,
@@ -136,7 +145,7 @@ class AstroBuilder {
 			{
 				settings: this.settings,
 				logger: this.logger,
-				mode: 'build',
+				mode: this.mode,
 				command: 'build',
 				sync: false,
 				manifest: this.manifest,
@@ -145,6 +154,7 @@ class AstroBuilder {
 
 		const { syncInternal } = await import('../sync/index.js');
 		await syncInternal({
+			mode: this.mode,
 			settings: this.settings,
 			logger,
 			fs,
@@ -193,7 +203,7 @@ class AstroBuilder {
 			settings: this.settings,
 			logger: this.logger,
 			manifest: this.manifest,
-			mode: this.mode,
+			runtimeMode: this.runtimeMode,
 			origin: this.origin,
 			pageNames,
 			teardownCompiler: this.teardownCompiler,

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

@@ -78,7 +78,7 @@ export class BuildPipeline extends Pipeline {
 		super(
 			options.logger,
 			manifest,
-			options.mode,
+			options.runtimeMode,
 			manifest.renderers,
 			resolve,
 			serverLike,

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

@@ -156,7 +156,6 @@ async function ssrBuild(
 	const { lastVitePlugins, vitePlugins } = await container.runBeforeHook('server', input);
 	const viteBuildConfig: vite.InlineConfig = {
 		...viteConfig,
-		mode: viteConfig.mode || 'production',
 		logLevel: viteConfig.logLevel ?? 'error',
 		build: {
 			target: 'esnext',
@@ -269,7 +268,6 @@ async function clientBuild(
 
 	const viteBuildConfig: vite.InlineConfig = {
 		...viteConfig,
-		mode: viteConfig.mode || 'production',
 		build: {
 			target: 'esnext',
 			...viteConfig.build,

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

@@ -30,7 +30,7 @@ export interface StaticBuildOptions {
 	settings: AstroSettings;
 	logger: Logger;
 	manifest: ManifestData;
-	mode: RuntimeMode;
+	runtimeMode: RuntimeMode;
 	origin: string;
 	pageNames: string[];
 	viteConfig: InlineConfig;

packages/astro/src/core/create-vite.ts

@@ -45,18 +45,18 @@ import { isObject } from './util.js';
 type CreateViteOptions = {
 	settings: AstroSettings;
 	logger: Logger;
-	// will be undefined when using `getViteConfig`
-	command?: 'dev' | 'build';
+	mode: string;
 	fs?: typeof nodeFs;
 	sync: boolean;
 	manifest: ManifestData;
+	ssrManifest?: SSRManifest;
 } & (
 	| {
-			mode: 'dev';
+			command: 'dev';
 			ssrManifest: SSRManifest;
 	  }
 	| {
-			mode: 'build';
+			command: 'build';
 			ssrManifest?: SSRManifest;
 	  }
 );
@@ -92,7 +92,7 @@ export async function createVite(
 ): Promise<vite.InlineConfig> {
 	const astroPkgsConfig = await crawlFrameworkPkgs({
 		root: fileURLToPath(settings.config.root),
-		isBuild: mode === 'build',
+		isBuild: command === 'build',
 		viteUserConfig: settings.config.vite,
 		isFrameworkPkgByJson(pkgJson) {
 			// Certain packages will trigger the checks below, but need to be external. A common example are SSR adapters
@@ -128,6 +128,7 @@ export async function createVite(
 	const commonConfig: vite.InlineConfig = {
 		// Tell Vite not to combine config from vite.config.js with our provided inline config
 		configFile: false,
+		mode,
 		cacheDir: fileURLToPath(new URL('./node_modules/.vite/', settings.config.root)), // using local caches allows Astro to be used in monorepos, etc.
 		clearScreen: false, // we want to control the output, not Vite
 		customLogger: createViteLogger(logger, settings.config.vite.logLevel),
@@ -144,7 +145,7 @@ export async function createVite(
 			astroScriptsPlugin({ settings }),
 			// The server plugin is for dev only and having it run during the build causes
 			// the build to run very slow as the filewatcher is triggered often.
-			mode === 'dev' && vitePluginAstroServer({ settings, logger, fs, manifest, ssrManifest }), // ssrManifest is only required in dev mode, where it gets created before a Vite instance is created, and get passed to this function
+			command === 'dev' && vitePluginAstroServer({ settings, logger, fs, manifest, ssrManifest }), // ssrManifest is only required in dev mode, where it gets created before a Vite instance is created, and get passed to this function
 			envVitePlugin({ settings }),
 			astroEnv({ settings, mode, sync }),
 			markdownVitePlugin({ settings, logger }),
@@ -156,10 +157,10 @@ export async function createVite(
 			astroScannerPlugin({ settings, logger, manifest }),
 			astroContentVirtualModPlugin({ fs, settings }),
 			astroContentImportPlugin({ fs, settings, logger }),
-			astroContentAssetPropagationPlugin({ mode, settings }),
+			astroContentAssetPropagationPlugin({ settings }),
 			vitePluginMiddleware({ settings }),
 			vitePluginSSRManifest(),
-			astroAssetsPlugin({ settings, logger, mode }),
+			astroAssetsPlugin({ settings }),
 			astroPrefetch({ settings }),
 			astroTransitions({ settings }),
 			astroDevToolbar({ settings, logger }),
@@ -186,7 +187,7 @@ export async function createVite(
 					: undefined, // disable HMR for test
 			watch: {
 				// Prevent watching during the build to speed it up
-				ignored: mode === 'build' ? ['**'] : undefined,
+				ignored: command === 'build' ? ['**'] : undefined,
 			},
 		},
 		resolve: {
@@ -221,7 +222,7 @@ export async function createVite(
 		},
 		ssr: {
 			noExternal: [...ALWAYS_NOEXTERNAL, ...astroPkgsConfig.ssr.noExternal],
-			external: [...(mode === 'dev' ? ONLY_DEV_EXTERNAL : []), ...astroPkgsConfig.ssr.external],
+			external: [...(command === 'dev' ? ONLY_DEV_EXTERNAL : []), ...astroPkgsConfig.ssr.external],
 		},
 		build: { assetsDir: settings.config.build.assets },
 	};

packages/astro/src/core/dev/container.ts

@@ -92,9 +92,9 @@ export async function createContainer({
 
 	warnMissingAdapter(logger, settings);
 
+	const mode = inlineConfig?.mode ?? 'development';
 	const viteConfig = await createVite(
 		{
-			mode: 'development',
 			server: { host, headers, open },
 			optimizeDeps: {
 				include: rendererClientEntries,
@@ -103,7 +103,7 @@ export async function createContainer({
 		{
 			settings,
 			logger,
-			mode: 'dev',
+			mode,
 			command: 'dev',
 			fs,
 			sync: false,
@@ -114,6 +114,7 @@ export async function createContainer({
 
 	await syncInternal({
 		settings,
+		mode,
 		logger,
 		skip: {
 			content: true,

packages/astro/src/core/render/route-cache.ts

@@ -88,11 +88,11 @@ interface RouteCacheEntry {
 export class RouteCache {
 	private logger: Logger;
 	private cache: Record<string, RouteCacheEntry> = {};
-	private mode: RuntimeMode;
+	private runtimeMode: RuntimeMode;
 
-	constructor(logger: Logger, mode: RuntimeMode = 'production') {
+	constructor(logger: Logger, runtimeMode: RuntimeMode = 'production') {
 		this.logger = logger;
-		this.mode = mode;
+		this.runtimeMode = runtimeMode;
 	}
 
 	/** Clear the cache. */
@@ -105,7 +105,7 @@ export class RouteCache {
 		// NOTE: This shouldn't be called on an already-cached component.
 		// Warn here so that an unexpected double-call of getStaticPaths()
 		// isn't invisible and developer can track down the issue.
-		if (this.mode === 'production' && this.cache[key]?.staticPaths) {
+		if (this.runtimeMode === 'production' && this.cache[key]?.staticPaths) {
 			this.logger.warn(null, `Internal Warning: route cache overwritten. (${key})`);
 		}
 		this.cache[key] = entry;

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

@@ -35,6 +35,7 @@ import { createRouteManifest } from '../routing/index.js';
 import { ensureProcessNodeEnv } from '../util.js';
 
 export type SyncOptions = {
+	mode: string;
 	/**
 	 * @internal only used for testing
 	 */
@@ -79,7 +80,14 @@ export default async function sync(
 		throw err;
 	}
 
-	return await syncInternal({ settings, logger, fs, force: inlineConfig.force, manifest });
+	return await syncInternal({
+		settings,
+		logger,
+		mode: 'production',
+		fs,
+		force: inlineConfig.force,
+		manifest,
+	});
 }
 
 /**
@@ -105,6 +113,7 @@ export async function clearContentLayerCache({
  * @experimental The JavaScript API is experimental
  */
 export async function syncInternal({
+	mode,
 	logger,
 	fs = fsMod,
 	settings,
@@ -120,7 +129,7 @@ export async function syncInternal({
 
 	try {
 		if (!skip?.content) {
-			await syncContentCollections(settings, { fs, logger, manifest });
+			await syncContentCollections(settings, { mode, fs, logger, manifest });
 			settings.timer.start('Sync content layer');
 			let store: MutableDataStore | undefined;
 			try {
@@ -208,7 +217,12 @@ function writeInjectedTypes(settings: AstroSettings, fs: typeof fsMod) {
  */
 async function syncContentCollections(
 	settings: AstroSettings,
-	{ logger, fs, manifest }: Required<Pick<SyncOptions, 'logger' | 'fs' | 'manifest'>>,
+	{
+		mode,
+		logger,
+		fs,
+		manifest,
+	}: Required<Pick<SyncOptions, 'mode' | 'logger' | 'fs' | 'manifest'>>,
 ): Promise<void> {
 	// Needed to load content config
 	const tempViteServer = await createServer(
@@ -219,7 +233,7 @@ async function syncContentCollections(
 				ssr: { external: [] },
 				logLevel: 'silent',
 			},
-			{ settings, logger, mode: 'build', command: 'build', fs, sync: true, manifest },
+			{ settings, logger, mode, command: 'build', fs, sync: true, manifest },
 		),
 	);
 

packages/astro/src/env/vite-plugin-env.ts

@@ -15,7 +15,7 @@ import { getEnvFieldType, validateEnvVariable } from './validators.js';
 
 interface AstroEnvPluginParams {
 	settings: AstroSettings;
-	mode: 'dev' | 'build' | string;
+	mode: string;
 	sync: boolean;
 }
 
@@ -28,11 +28,7 @@ export function astroEnv({ settings, mode, sync }: AstroEnvPluginParams): Plugin
 		name: 'astro-env-plugin',
 		enforce: 'pre',
 		buildStart() {
-			const loadedEnv = loadEnv(
-				mode === 'dev' ? 'development' : 'production',
-				fileURLToPath(settings.config.root),
-				'',
-			);
+			const loadedEnv = loadEnv(mode, fileURLToPath(settings.config.root), '');
 			(globalThis as any)[ENV_SYMBOL] = loadedEnv;
 
 			const validatedVariables = validatePublicVariables({

packages/astro/src/types/public/config.ts

@@ -1711,9 +1711,15 @@ export interface AstroInlineOnlyConfig {
 	 */
 	configFile?: string | false;
 	/**
-	 * The mode used when building your site to generate either "development" or "production" code.
+	 * The mode used when developing or building your site. It's passed to Vite that affects the value of `import.meta.env.MODE`
+	 * and how `.env` files are loaded, which also affects the values of `astro:env`. See the
+	 * [environment variables documentation](https://docs.astro.build/en/guides/environment-variables/) for more details.
+	 *
+	 * To output a development-based build, you can run `astro build` with the `--devOutput` flag.
+	 *
+	 * @default "development" for `astro dev`, "production" for `astro build`
 	 */
-	mode?: RuntimeMode;
+	mode?: string;
 	/**
 	 * The logging level to filter messages logged by Astro.
 	 * - "debug": Log everything, including noisy debugging diagnostics.

packages/astro/src/vite-plugin-astro-server/pipeline.ts

@@ -45,11 +45,10 @@ export class DevPipeline extends Pipeline {
 		readonly config = settings.config,
 		readonly defaultRoutes = createDefaultRoutes(manifest),
 	) {
-		const mode = 'development';
 		const resolve = createResolve(loader, config.root);
 		const serverLike = settings.buildOutput === 'server';
 		const streaming = true;
-		super(logger, manifest, mode, [], resolve, serverLike, streaming);
+		super(logger, manifest, 'development', [], resolve, serverLike, streaming);
 		manifest.serverIslandMap = settings.serverIslandMap;
 		manifest.serverIslandNameMap = settings.serverIslandNameMap;
 	}
@@ -72,14 +71,14 @@ export class DevPipeline extends Pipeline {
 		const {
 			config: { root },
 			loader,
-			mode,
+			runtimeMode,
 			settings,
 		} = this;
 		const filePath = new URL(`${routeData.component}`, root);
 		const scripts = new Set<SSRElement>();
 
 		// Inject HMR scripts
-		if (isPage(filePath, settings) && mode === 'development') {
+		if (isPage(filePath, settings) && runtimeMode === 'development') {
 			scripts.add({
 				props: { type: 'module', src: '/@vite/client' },
 				children: '',

packages/astro/test/astro-mode.test.js

@@ -0,0 +1,119 @@
+import assert from 'node:assert/strict';
+import { after, afterEach, before, describe, it } from 'node:test';
+import * as cheerio from 'cheerio';
+import { loadFixture } from './test-utils.js';
+
+describe('--mode', () => {
+	/** @type {import('./test-utils.js').Fixture} */
+	let fixture;
+
+	before(async () => {
+		fixture = await loadFixture({
+			root: './fixtures/astro-mode/',
+		});
+	});
+
+	afterEach(() => {
+		// Reset so it doesn't interfere with other tests as builds below
+		// will interact with env variables loaded from .env files
+		delete process.env.NODE_ENV;
+		// `astro:env` writes to `process.env` currently which should be avoided,
+		// otherwise consecutive builds can't get the latest `.env` values. Workaround
+		// here for now be resetting it.
+		delete process.env.TITLE;
+	});
+
+	describe('build', () => {
+		before(async () => {
+			await fixture.build();
+		});
+
+		it('works', async () => {
+			const html = await fixture.readFile('/index.html');
+			const $ = cheerio.load(html);
+			assert.equal($('#env-mode').text(), 'production');
+			assert.equal($('#env-dev').text(), 'false');
+			assert.equal($('#env-prod').text(), 'true');
+			assert.equal($('#env-title').text(), 'production');
+			assert.equal($('#env-astro-title').text(), 'production');
+		});
+	});
+
+	describe('build --mode testing --devOutput', () => {
+		before(async () => {
+			await fixture.build({ mode: 'testing' }, { devOutput: true });
+		});
+
+		it('works', async () => {
+			const html = await fixture.readFile('/index.html');
+			const $ = cheerio.load(html);
+			assert.equal($('#env-mode').text(), 'testing');
+			assert.equal($('#env-dev').text(), 'true');
+			assert.equal($('#env-prod').text(), 'false');
+			assert.equal($('#env-title').text(), '');
+			assert.equal($('#env-astro-title').text(), 'unset');
+		});
+	});
+
+	describe('build --mode staging', () => {
+		before(async () => {
+			await fixture.build({ mode: 'staging' });
+		});
+
+		it('works', async () => {
+			const html = await fixture.readFile('/index.html');
+			const $ = cheerio.load(html);
+			assert.equal($('#env-mode').text(), 'staging');
+			assert.equal($('#env-dev').text(), 'false');
+			assert.equal($('#env-prod').text(), 'true');
+			assert.equal($('#env-title').text(), 'staging');
+			assert.equal($('#env-astro-title').text(), 'staging');
+		});
+	});
+
+	describe('dev', () => {
+		/** @type {import('./test-utils.js').DevServer} */
+		let devServer;
+		before(async () => {
+			devServer = await fixture.startDevServer();
+		});
+		after(async () => {
+			await devServer.stop();
+		});
+
+		it('works', async () => {
+			const res = await fixture.fetch('/');
+			assert.equal(res.status, 200);
+			const html = await res.text();
+			const $ = cheerio.load(html);
+			assert.equal($('#env-mode').text(), 'development');
+			assert.equal($('#env-dev').text(), 'true');
+			assert.equal($('#env-prod').text(), 'false');
+			assert.equal($('#env-title').text(), 'development');
+			assert.equal($('#env-astro-title').text(), 'development');
+		});
+	});
+
+	describe('dev --mode develop', () => {
+		/** @type {import('./test-utils.js').DevServer} */
+		let devServer;
+		before(async () => {
+			devServer = await fixture.startDevServer({ mode: 'develop' });
+		});
+		after(async () => {
+			await devServer.stop();
+		});
+
+		it('works', async () => {
+			const res = await fixture.fetch('/');
+			assert.equal(res.status, 200);
+			const html = await res.text();
+			const $ = cheerio.load(html);
+			assert.equal($('#env-mode').text(), 'develop');
+			assert.equal($('#env-dev').text(), 'true');
+			assert.equal($('#env-prod').text(), 'false');
+			assert.equal($('#env-title').text(), '');
+			assert.equal($('#env-astro-title').text(), 'unset');
+		});
+	});
+});

packages/astro/test/fixtures/astro-mode/.env.development

@@ -0,0 +1 @@
+TITLE=development

packages/astro/test/fixtures/astro-mode/.env.production

@@ -0,0 +1 @@
+TITLE=production

packages/astro/test/fixtures/astro-mode/.env.staging

@@ -0,0 +1 @@
+TITLE=staging

packages/astro/test/fixtures/astro-mode/astro.config.mjs

@@ -0,0 +1,14 @@
+import { defineConfig, envField } from 'astro/config';
+
+export default defineConfig({
+	env: {
+		schema: {
+			TITLE: envField.string({
+				context: 'client',
+				access: 'public',
+				optional: true,
+				default: 'unset',
+			}),
+		},
+	},
+});

packages/astro/test/fixtures/astro-mode/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@test/astro-mode",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "astro": "workspace:*"
+  }
+}

packages/astro/test/fixtures/astro-mode/src/pages/index.astro

@@ -0,0 +1,9 @@
+---
+import { TITLE } from 'astro:env/client';
+---
+
+<div id="env-mode">{import.meta.env.MODE}</div>
+<div id="env-dev">{import.meta.env.DEV.toString()}</div>
+<div id="env-prod">{import.meta.env.PROD.toString()}</div>
+<div id="env-title">{import.meta.env.TITLE}</div>
+<div id="env-astro-title">{TITLE}</div>

packages/astro/test/test-utils.js

@@ -162,7 +162,8 @@ export async function loadFixture(inlineConfig) {
 		build: async (extraInlineConfig = {}, options = {}) => {
 			globalContentLayer.dispose();
 			globalContentConfigObserver.set({ status: 'init' });
-			process.env.NODE_ENV = 'production';
+			// Reset NODE_ENV so it can be re-set by `build()`
+			delete process.env.NODE_ENV;
 			return build(mergeConfig(inlineConfig, extraInlineConfig), {
 				teardownCompiler: false,
 				...options,
@@ -175,7 +176,8 @@ export async function loadFixture(inlineConfig) {
 		startDevServer: async (extraInlineConfig = {}) => {
 			globalContentLayer.dispose();
 			globalContentConfigObserver.set({ status: 'init' });
-			process.env.NODE_ENV = 'development';
+			// Reset NODE_ENV so it can be re-set by `dev()`
+			delete process.env.NODE_ENV;
 			devServer = await dev(mergeConfig(inlineConfig, extraInlineConfig));
 			config.server.host = parseAddressToHost(devServer.address.address); // update host
 			config.server.port = devServer.address.port; // update port
@@ -233,7 +235,8 @@ export async function loadFixture(inlineConfig) {
 			}
 		},
 		preview: async (extraInlineConfig = {}) => {
-			process.env.NODE_ENV = 'production';
+			// Reset NODE_ENV so it can be re-set by `preview()`
+			delete process.env.NODE_ENV;
 			const previewServer = await preview(mergeConfig(inlineConfig, extraInlineConfig));
 			config.server.host = parseAddressToHost(previewServer.host); // update host
 			config.server.port = previewServer.port; // update port

pnpm-lock.yaml

@@ -2218,6 +2218,12 @@ importers:
         specifier: workspace:*
         version: link:../../..
 
+  packages/astro/test/fixtures/astro-mode:
+    dependencies:
+      astro:
+        specifier: workspace:*
+        version: link:../../..
+
   packages/astro/test/fixtures/astro-not-response:
     dependencies:
       astro: