feat: experimental static import.meta.env (#12105)

Co-authored-by: Armand Philippot <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>
Co-authored-by: Yan <[email protected]>
Co-authored-by: louisescher <[email protected]>

Author: 5 people

astro.sidebar.ts

@@ -149,7 +149,7 @@ export const sidebar = [
 					'reference/experimental-flags/content-intellisense',
 					'reference/experimental-flags/preserve-scripts-order',
 					'reference/experimental-flags/heading-id-compat',
-					'reference/experimental-flags/raw-env-values',
+					'reference/experimental-flags/static-import-meta-env',
 					'reference/experimental-flags/chrome-devtools-workspace',
 				],
 			}),

src/content/docs/en/reference/experimental-flags/raw-env-values.mdx

@@ -0,0 +1,88 @@
+---
+title: Experimental private meta environment variables inlining
+sidebar:
+  label: Private meta environment variables inlining
+i18nReady: true
+---
+
+import Since from '~/components/Since.astro'
+
+<p>
+
+**Type:** `boolean`<br />
+**Default:** `false`<br />
+<Since v="5.13.0" />
+</p>
+
+:::tip[Astro 6.0 preview]
+The behavior enabled by this feature will become the default behavior in Astro 6.0.
+
+You may wish to add this flag whenever it is convenient to do so. You can start enjoying the benefits sooner and will avoid the need to update your project code for the next major Astro version.
+:::
+
+Astro allows you to configure a [type-safe schema for your environment variables](/en/guides/environment-variables/#type-safe-environment-variables), and converts variables imported via `astro:env` into the expected type. This is the recommended way to use environment variables in Astro, as it allows you to easily see and manage whether your variables are public or secret, available on the client or only on the server at build time, and the data type of your values.
+
+However, you can still access your environment variables through `process.env` as well as `import.meta.env` directly if needed. This was the only way to use environment variables in Astro before `astro:env` was added in Astro 5.0, and its handling of `import.meta.env` includes some logic that was intended for earlier versions of Astro that is no longer necessary.
+
+The `experimental.staticImportMetaEnv` flag updates the behavior when accessing `import.meta.env` directly to align with [Vite's handling of environment variables](https://vite.dev/guide/env-and-mode.html#env-variables) and ensures that `import.meta.env` values are always inlined.
+
+Currently, non-public environment variables are replaced by a reference to `process.env`. Additionally, Astro may also convert the value type of your environment variables used through `import.meta.env`, which can prevent access to some values such as the strings `"true"` (which is converted to a boolean value), and `"1"` (which is converted to a number).
+
+The `experimental.staticImportMetaEnv` flag simplifies Astro's default behavior, making it easier to understand and use. Astro will no longer replace any `import.meta.env` environment variables with a `process.env` call, nor will it coerce values.
+
+To enable this feature, add the experimental flag in your Astro config:
+
+```js title="astro.config.mjs" ins={4-6}
+import { defineConfig } from "astro/config"
+
+export default defineConfig({
+  experimental: {
+    staticImportMetaEnv: true,
+  }
+})
+```
+
+## Usage
+
+Enabling this experimental flag will no longer convert string values into booleans or numbers, nor turn `import.meta.env` values into `process.env` calls. This aligns `import.meta.env`'s behavior in Astro with [Vite](https://vite.dev/guide/env-and-mode.html#env-variables).
+
+In a future major version, Astro will switch to this behavior by default, but you can opt in to the future behavior early using the `experimental.staticImportMetaEnv` flag and, if necessary, [updating your project](#updating-your-project) accordingly.
+
+### Updating your project
+
+If you were relying on coercion, you may need to update your project code to apply it manually:
+
+```ts title="src/components/MyComponent.astro" del={1} ins={2}
+const enabled: boolean = import.meta.env.ENABLED;
+const enabled: boolean = import.meta.env.ENABLED === "true";
+```
+
+If you were relying on the transformation into `process.env`, you may need to update your project code to apply it manually:
+
+```ts title="src/components/MyComponent.astro" del={1} ins={2}
+const enabled: boolean = import.meta.env.DB_PASSWORD;
+const enabled: boolean = process.env.DB_PASSWORD;
+```
+
+You may also need to update types:
+
+```ts title="src/env.d.ts" del={3-4} ins={5,12-16}
+interface ImportMetaEnv {
+  readonly PUBLIC_POKEAPI: string;
+  readonly DB_PASSWORD: string;
+  readonly ENABLED: boolean;
+  readonly ENABLED: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+
+namespace NodeJS {
+  interface ProcessEnv {
+    DB_PASSWORD: string;
+  }
+}
+```
+
+If you need more control over environment variables in Astro, we recommend you use [`astro:env`](/en/guides/environment-variables/).