[v6] stabilize experimental.staticImportMetaEnv (#12494)

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

Author: florian-lefebvre

astro.sidebar.ts

@@ -148,7 +148,6 @@ export const sidebar = [
 					'reference/experimental-flags/client-prerender',
 					'reference/experimental-flags/content-intellisense',
 					'reference/experimental-flags/heading-id-compat',
-					'reference/experimental-flags/static-import-meta-env',
 					'reference/experimental-flags/chrome-devtools-workspace',
 				],
 			}),

src/content/docs/en/guides/upgrade-to/v6.mdx

@@ -380,19 +380,21 @@ The following experimental flags have been removed in Astro v6.0 and these featu
 Additionally, the following experimental flags have been removed and **are now the default or recommended behavior in Astro v6.0**.
 
 - `experimental.preserveScriptOrder` (See below for breaking changes to [default `<script>` and `<style>` behavior](#changed-script-and-style-tags-are-rendered-in-the-order-they-are-defined).)
+- `experimental.staticImportMetaEnv` (See below for breaking changes to [`import.meta.env`](#changed-importmetaenv-values-are-always-inlined).)
 
 The following experimental flags have been removed and **their corresponding features are not part of Astro v6.0**.
 
 - `thing 2`
 
 Remove these experimental flags from your Astro config if you were previously using them:
 
-```js del={5} title="astro.config.mjs"
+```js del={5-6} title="astro.config.mjs"
 import { defineConfig } from 'astro/config';
 
 export default defineConfig({
   experimental: {
     preserveScriptOrder: true,
+    staticImportMetaEnv: true,
   },
 })
 ```
@@ -498,6 +500,59 @@ Review your links to your custom endpoints that include a file extension in the
 
 <ReadMore>Learn more about [custom endpoints](/en/guides/endpoints/).</ReadMore>
 
+### Changed: `import.meta.env` values are always inlined
+
+<SourcePR number="14485" title="feat: stabilize static import meta env"/>
+
+In Astro 5.13, the `experimental.staticImportMetaEnv` was introduced to update 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.
+
+In Astro 5.x, non-public environment variables were replaced by a reference to `process.env`. Additionally, Astro could also convert the value type of your environment variables used through `import.meta.env`, which could prevent access to some values such as the strings `"true"` (which was converted to a boolean value), and `"1"` (which was converted to a number).
+
+Astro 6 removes this experimental flag and makes this the new default behavior in Astro: `import.meta.env` values are always inlined and never coerced.
+
+#### What should I do?
+
+If you were previously using this experimental feature, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists.
+
+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`.
+
+<ReadMore>Learn more about [environment variables](/en/guides/environment-variables/) in Astro, including `astro:env`.</ReadMore>
+
 ## Community Resources
 
 Know a good resource for Astro v5.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v6.mdx) and add a link below!