withastro · bluwy · Oct 7, 2024
diff --git a/.changeset/sixty-coins-worry.md b/.changeset/sixty-coins-worry.md
@@ -0,0 +1,29 @@
+---
+'astro': minor
+---
+
+Adds support for passing values other than `"production"` or `"development"` to the `--mode` flag, e.g. `"staging"`, `"testing"`, or any value. This allows to change the value of `import.meta.env.MODE` or the loaded `.env` file, and take advantage of Vite's [mode](https://vite.dev/guide/env-and-mode#modes) feature.
+
+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 --dev` (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 --dev
+
+# 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 have different `API_URL` environment variable values (for example).
diff --git a/packages/astro/src/assets/vite-plugin-assets.ts b/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

diff --git a/packages/astro/src/cli/build/index.ts b/packages/astro/src/cli/build/index.ts
@@ -18,6 +18,7 @@ export async function build({ flags }: BuildOptions) {
 						'--force',
 						'Clear the content layer and content collection cache, forcing a full rebuild.',
 					],
+					['--dev', 'Create a development build, similar to code transformed in `astro dev`.'],
 					['--help (-h)', 'See all available flags.'],
 				],
 			},
@@ -28,5 +29,5 @@ export async function build({ flags }: BuildOptions) {
 
 	const inlineConfig = flagsToAstroInlineConfig(flags);
 
-	await _build(inlineConfig);
+	await _build(inlineConfig, { dev: !!flags.dev });
 }
diff --git a/packages/astro/src/cli/flags.ts b/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,
 

diff --git a/packages/astro/src/config/index.ts b/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);

diff --git a/packages/astro/src/content/vite-plugin-content-assets.ts b/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)) {

diff --git a/packages/astro/src/content/vite-plugin-content-virtual-mod.ts b/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) {

diff --git a/packages/astro/src/core/app/index.ts b/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) => {

diff --git a/packages/astro/src/core/app/pipeline.ts b/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,

diff --git a/packages/astro/src/core/base-pipeline.ts b/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`.
 		 */

diff --git a/packages/astro/src/core/build/index.ts b/packages/astro/src/core/build/index.ts
@@ -31,7 +31,14 @@ 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 {
+	/**
+	 * Create a development build, similar to code transformed in `astro dev`.
+	 *
+	 * @default false
+	 */
+	dev?: 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 +59,7 @@ export default async function build(
 	inlineConfig: AstroInlineConfig,
 	options: BuildOptions = {},
 ): Promise<void> {
-	ensureProcessNodeEnv('production');
+	ensureProcessNodeEnv(options.dev ? 'development' : 'production');
 	applyPolyfill();
 	const logger = createNodeLogger(inlineConfig);
 	const { userConfig, astroConfig } = await resolveConfig(inlineConfig, 'build');
@@ -67,29 +74,31 @@ export default async function build(
 	const builder = new AstroBuilder(settings, {
 		...options,
 		logger,
-		mode: inlineConfig.mode,
+		mode: inlineConfig.mode ?? 'production',
+		runtimeMode: options.dev ? '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 +136,6 @@ class AstroBuilder {
 
 		const viteConfig = await createVite(
 			{
-				mode: this.mode,
 				server: {
 					hmr: false,
 					middlewareMode: true,
@@ -136,7 +144,7 @@ class AstroBuilder {
 			{
 				settings: this.settings,
 				logger: this.logger,
-				mode: 'build',
+				mode: this.mode,
 				command: 'build',
 				sync: false,
 				manifest: this.manifest,
@@ -145,6 +153,7 @@ class AstroBuilder {
 
 		const { syncInternal } = await import('../sync/index.js');
 		await syncInternal({
+			mode: this.mode,
 			settings: this.settings,
 			logger,
 			fs,
@@ -193,7 +202,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,

diff --git a/packages/astro/src/core/build/pipeline.ts b/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,

diff --git a/packages/astro/src/core/build/static-build.ts b/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,

diff --git a/packages/astro/src/core/build/types.ts b/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;