feat: experimental static import.meta.env

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/legacy-flags',

src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx

@@ -0,0 +1,78 @@
+---
+title: Experimental static import.meta.env
+sidebar:
+  label: Static import.meta.env
+i18nReady: true
+---
+
+import Since from '~/components/Since.astro'
+
+<p>
+
+**Type:** `boolean`<br />
+**Default:** `false`<br />
+<Since v="5.13.0" />
+</p>
+
+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.
+
+However, Astro by default turns non public `import.meta.env` values into `process.env` calls during the build, if the environment variable name is present in `process.env`. It also converts your environment variables used through `import.meta.env` in some cases, and this 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 disables this behavior, ensuring that `import.meta.env` values are always inlined.
+
+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 need to update types as well:
+
+```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/).