feat(next): make astro:env stable

.changeset/eighty-boxes-applaud.md

@@ -0,0 +1,21 @@
+---
+'astro': major
+---
+
+Makes `astro:env` stable
+
+To upgrade, update your Astro config:
+
+```diff
+import { defineConfig, envField } from 'astro/config'
+
+export default defineConfig({
+-    experimental: {
+        env: {
+            schema: {
+                FOO: envField.string({ /* ... */ })
+            }
+        }
+-    }
+})
+```

.changeset/selfish-impalas-grin.md

@@ -0,0 +1,6 @@
+---
+'@astrojs/vercel': major
+'@astrojs/node': major
+---
+
+Adds stable support for `astro:env`

packages/astro/client.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="vite/types/import-meta.d.ts" />
 /// <reference path="./types/content.d.ts" />
 /// <reference path="./types/actions.d.ts" />
+/// <reference path="./types/env.d.ts" />
 
 // eslint-disable-next-line  @typescript-eslint/no-namespace
 declare namespace App {

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

@@ -1755,6 +1755,76 @@ export interface AstroUserConfig {
 	 */
 	legacy?: object;
 
+	/**
+	 * @docs
+	 * @name env
+	 * @type {object}
+	 * @default `{}`
+	 * @version 5.0.0
+	 * @description
+	 *
+	 * Holds `astro:env` options.
+	 */
+	env?: {
+		/**
+		 * @docs
+		 * @name env.schema
+		 * @type {EnvSchema}
+		 * @default `{}`
+		 * @version 5.0.0
+		 * @description
+		 *
+		 * An object that uses `envField` to define the data type (`string`, `number`, or `boolean`) and properties of your environment variables: `context` (client or server), `access` (public or secret), a `default` value to use, and whether or not this environment variable is `optional` (defaults to `false`).
+		 * ```js
+		 * // astro.config.mjs
+		 * import { defineConfig, envField } from "astro/config"
+		 *
+		 * export default defineConfig({
+		 *   experimental: {
+		 *     env: {
+		 *       schema: {
+		 *         API_URL: envField.string({ context: "client", access: "public", optional: true }),
+		 *         PORT: envField.number({ context: "server", access: "public", default: 4321 }),
+		 *         API_SECRET: envField.string({ context: "server", access: "secret" }),
+		 *       }
+		 *     }
+		 *   }
+		 * })
+		 * ```
+		 */
+		schema?: EnvSchema;
+
+		/**
+		 * @docs
+		 * @name env.validateSecrets
+		 * @type {boolean}
+		 * @default `false`
+		 * @version 5.0.0
+		 * @description
+		 *
+		 * Whether or not to validate secrets on the server when starting the dev server or running a build.
+		 *
+		 * By default, only public variables are validated on the server when starting the dev server or a build, and private variables are validated at runtime only. If enabled, private variables will also be checked on start. This is useful in some continuous integration (CI) pipelines to make sure all your secrets are correctly set before deploying.
+		 *
+		 * ```js
+		 * // astro.config.mjs
+		 * import { defineConfig, envField } from "astro/config"
+		 *
+		 * export default defineConfig({
+		 *   experimental: {
+		 *     env: {
+		 *       schema: {
+		 *         // ...
+		 *       },
+		 *       validateSecrets: true
+		 *     }
+		 *   }
+		 * })
+		 * ```
+		 */
+		validateSecrets?: boolean;
+	};
+
 	/**
 	 * @docs
 	 * @kind heading
@@ -1977,148 +2047,6 @@ export interface AstroUserConfig {
 		 */
 		globalRoutePriority?: boolean;
 
-		/**
-		 * @docs
-		 * @name experimental.env
-		 * @type {object}
-		 * @default `undefined`
-		 * @version 4.10.0
-		 * @description
-		 *
-		 * Enables experimental `astro:env` features.
-		 *
-		 * The `astro:env` API lets you configure a type-safe schema for your environment variables, and indicate whether they should be available on the server or the client. Import and use your defined variables from the appropriate `/client` or `/server` module:
-		 *
-		 * ```astro
-		 * ---
-		 * import { API_URL } from "astro:env/client"
-		 * import { API_SECRET_TOKEN } from "astro:env/server"
-		 *
-		 * const data = await fetch(`${API_URL}/users`, {
-		 * 	method: "GET",
-		 * 	headers: {
-		 * 		"Content-Type": "application/json",
-		 * 		"Authorization": `Bearer ${API_SECRET_TOKEN}`
-		 * 	},
-		 * })
-		 * ---
-		 *
-		 * <script>
-		 * import { API_URL } from "astro:env/client"
-		 *
-		 * fetch(`${API_URL}/ping`)
-		 * </script>
-		 * ```
-		 *
-		 * To define the data type and properties of your environment variables, declare a schema in your Astro config in `experimental.env.schema`. The `envField` helper allows you define your variable as a string, number, or boolean and pass properties in an object:
-		 *
-		 * ```js
-		 * // astro.config.mjs
-		 * import { defineConfig, envField } from "astro/config"
-		 *
-		 * export default defineConfig({
-		 *     experimental: {
-		 *         env: {
-		 *             schema: {
-		 *                 API_URL: envField.string({ context: "client", access: "public", optional: true }),
-		 *                 PORT: envField.number({ context: "server", access: "public", default: 4321 }),
-		 *                 API_SECRET: envField.string({ context: "server", access: "secret" }),
-		 *             }
-		 *         }
-		 *     }
-		 * })
-		 * ```
-		 *
-		 * There are currently four data types supported: strings, numbers, booleans and enums.
-		 *
-		 * There are three kinds of environment variables, determined by the combination of `context` (client or server) and `access` (secret or public) settings defined in your [`env.schema`](#experimentalenvschema):
-		 *
-		 * - **Public client variables**: These variables end up in both your final client and server bundles, and can be accessed from both client and server through the `astro:env/client` module:
-		 *
-		 *     ```js
-		 *     import { API_URL } from "astro:env/client"
-		 *     ```
-		 *
-		 * - **Public server variables**: These variables end up in your final server bundle and can be accessed on the server through the `astro:env/server` module:
-		 *
-		 *     ```js
-		 *     import { PORT } from "astro:env/server"
-		 *     ```
-		 *
-		 * - **Secret server variables**: These variables are not part of your final bundle and can be accessed on the server through the `astro:env/server` module. The `getSecret()` helper function can be used to retrieve secrets not specified in the schema. Its implementation is provided by your adapter and defaults to `process.env`:
-		 *
-		 *     ```js
-		 *     import { API_SECRET, getSecret } from "astro:env/server"
-		 *
-		 *     const SECRET_NOT_IN_SCHEMA = getSecret("SECRET_NOT_IN_SCHEMA") // string | undefined
-		 *     ```
-		 *
-		 * **Note:** Secret client variables are not supported because there is no safe way to send this data to the client. Therefore, it is not possible to configure both `context: "client"` and `access: "secret"` in your schema.
-		 *
-		 * For a complete overview, and to give feedback on this experimental API, see the [Astro Env RFC](https://github.com/withastro/roadmap/blob/feat/astro-env-rfc/proposals/0046-astro-env.md).
-		 */
-		env?: {
-			/**
-			 * @docs
-			 * @name experimental.env.schema
-			 * @kind h4
-			 * @type {EnvSchema}
-			 * @default `undefined`
-			 * @version 4.10.0
-			 * @description
-			 *
-			 * An object that uses `envField` to define the data type (`string`, `number`, or `boolean`) and properties of your environment variables: `context` (client or server), `access` (public or secret), a `default` value to use, and whether or not this environment variable is `optional` (defaults to `false`).
-			 * ```js
-			 * // astro.config.mjs
-			 * import { defineConfig, envField } from "astro/config"
-			 *
-			 * export default defineConfig({
-			 *   experimental: {
-			 *     env: {
-			 *       schema: {
-			 *         API_URL: envField.string({ context: "client", access: "public", optional: true }),
-			 *         PORT: envField.number({ context: "server", access: "public", default: 4321 }),
-			 *         API_SECRET: envField.string({ context: "server", access: "secret" }),
-			 *       }
-			 *     }
-			 *   }
-			 * })
-			 * ```
-			 */
-			schema?: EnvSchema;
-
-			/**
-			 * @docs
-			 * @name experimental.env.validateSecrets
-			 * @kind h4
-			 * @type {boolean}
-			 * @default `false`
-			 * @version 4.11.6
-			 * @description
-			 *
-			 * Whether or not to validate secrets on the server when starting the dev server or running a build.
-			 *
-			 * By default, only public variables are validated on the server when starting the dev server or a build, and private variables are validated at runtime only. If enabled, private variables will also be checked on start. This is useful in some continuous integration (CI) pipelines to make sure all your secrets are correctly set before deploying.
-			 *
-			 * ```js
-			 * // astro.config.mjs
-			 * import { defineConfig, envField } from "astro/config"
-			 *
-			 * export default defineConfig({
-			 *   experimental: {
-			 *     env: {
-			 *       schema: {
-			 *         // ...
-			 *       },
-			 *       validateSecrets: true
-			 *     }
-			 *   }
-			 * })
-			 * ```
-			 */
-			validateSecrets?: boolean;
-		};
-
 		/**
 		 * @docs
 		 * @name experimental.serverIslands

packages/astro/src/container/index.ts

@@ -129,7 +129,7 @@ function createManifest(
 		i18n: manifest?.i18n,
 		checkOrigin: false,
 		middleware: manifest?.middleware ?? middleware ?? defaultMiddleware,
-		experimentalEnvGetSecretEnabled: false,
+		envGetSecretEnabled: false,
 	};
 }
 

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

@@ -69,8 +69,7 @@ export type SSRManifest = {
 	i18n: SSRManifestI18n | undefined;
 	middleware: MiddlewareHandler;
 	checkOrigin: boolean;
-	// TODO: remove experimental prefix
-	experimentalEnvGetSecretEnabled: boolean;
+	envGetSecretEnabled: boolean;
 };
 
 export type SSRManifestI18n = {

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

@@ -69,7 +69,7 @@ export abstract class Pipeline {
 		}
 		// In SSR, getSecret should fail by default. Setting it here will run before the
 		// adapter override.
-		if (callSetGetEnv && manifest.experimentalEnvGetSecretEnabled) {
+		if (callSetGetEnv && manifest.envGetSecretEnabled) {
 			setGetEnv(() => {
 				throw new AstroError(AstroErrorData.EnvUnsupportedGetSecret);
 			}, true);

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

@@ -551,6 +551,6 @@ function createBuildManifest(
 		buildFormat: settings.config.build.format,
 		middleware,
 		checkOrigin: settings.config.security?.checkOrigin ?? false,
-		experimentalEnvGetSecretEnabled: false,
+		envGetSecretEnabled: false,
 	};
 }

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

@@ -16,11 +16,6 @@ export function vitePluginChunks(): VitePlugin {
 					if (id.includes('astro/dist/runtime')) {
 						return 'astro';
 					}
-					// Place `astro/env/setup` import in its own chunk to prevent Rollup's TLA bug
-					// https://github.com/rollup/rollup/issues/4708
-					if (id.includes('astro/dist/env/setup')) {
-						return 'astro/env-setup';
-					}
 				},
 			});
 		},

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

@@ -277,8 +277,7 @@ function buildManifest(
 		buildFormat: settings.config.build.format,
 		checkOrigin: settings.config.security?.checkOrigin ?? false,
 		serverIslandNameMap: Array.from(settings.serverIslandNameMap),
-		experimentalEnvGetSecretEnabled:
-			settings.config.experimental.env !== undefined &&
+		envGetSecretEnabled:
 			(settings.adapter?.supportedAstroFeatures.envGetSecret ?? 'unsupported') !== 'unsupported',
 	};
 }

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

@@ -82,16 +82,17 @@ export const ASTRO_CONFIG_DEFAULTS = {
 	legacy: {},
 	redirects: {},
 	security: {},
+	env: {
+		schema: {},
+		validateSecrets: false,
+	},
 	experimental: {
 		actions: false,
 		directRenderScript: false,
 		contentCollectionCache: false,
 		clientPrerender: false,
 		globalRoutePriority: false,
 		serverIslands: false,
-		env: {
-			validateSecrets: false,
-		},
 	},
 } satisfies AstroUserConfig & { server: { open: boolean } };
 
@@ -505,6 +506,14 @@ export const AstroConfigSchema = z.object({
 		})
 		.optional()
 		.default(ASTRO_CONFIG_DEFAULTS.security),
+	env: z
+		.object({
+			schema: EnvSchema.optional().default(ASTRO_CONFIG_DEFAULTS.env.schema),
+			validateSecrets: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.env.validateSecrets),
+		})
+		.strict()
+		.optional()
+		.default(ASTRO_CONFIG_DEFAULTS.env),
 	experimental: z
 		.object({
 			actions: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.experimental.actions),
@@ -524,16 +533,6 @@ export const AstroConfigSchema = z.object({
 				.boolean()
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.globalRoutePriority),
-			env: z
-				.object({
-					schema: EnvSchema.optional(),
-					validateSecrets: z
-						.boolean()
-						.optional()
-						.default(ASTRO_CONFIG_DEFAULTS.experimental.env.validateSecrets),
-				})
-				.strict()
-				.optional(),
 			serverIslands: z
 				.boolean()
 				.optional()

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

@@ -133,7 +133,7 @@ export async function createVite(
 			// the build to run very slow as the filewatcher is triggered often.
 			mode !== 'build' && vitePluginAstroServer({ settings, logger, fs }),
 			envVitePlugin({ settings }),
-			astroEnv({ settings, mode, fs, sync }),
+			astroEnv({ settings, mode, sync }),
 			markdownVitePlugin({ settings, logger }),
 			htmlVitePlugin(),
 			mdxVitePlugin(),

packages/astro/src/core/sync/setup-env-ts.ts

@@ -48,12 +48,10 @@ export async function setUpEnvTs({
 			filename: ACTIONS_TYPES_FILE,
 			meetsCondition: () => fs.existsSync(new URL(ACTIONS_TYPES_FILE, settings.dotAstroDir)),
 		},
-	];
-	if (settings.config.experimental.env) {
-		injectedTypes.push({
+		{
 			filename: ENV_TYPES_FILE,
-		});
-	}
+		},
+	];
 
 	if (fs.existsSync(envTsPath)) {
 		const initialEnvContents = await fs.promises.readFile(envTsPath, 'utf-8');