From d11b42ec1ab2e8364b6597bc58b0ed98554a32f9 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Fri, 1 Aug 2025 09:45:38 +0200 Subject: [PATCH 01/10] feat: experimental static import.meta.env --- astro.sidebar.ts | 2 +- .../experimental-flags/raw-env-values.mdx | 50 ------------ .../static-import-meta-env.mdx | 78 +++++++++++++++++++ 3 files changed, 79 insertions(+), 51 deletions(-) delete mode 100644 src/content/docs/en/reference/experimental-flags/raw-env-values.mdx create mode 100644 src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx diff --git a/astro.sidebar.ts b/astro.sidebar.ts index 23849daea8363..00e96aac6c249 100644 --- a/astro.sidebar.ts +++ b/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', diff --git a/src/content/docs/en/reference/experimental-flags/raw-env-values.mdx b/src/content/docs/en/reference/experimental-flags/raw-env-values.mdx deleted file mode 100644 index fc3e89f61d750..0000000000000 --- a/src/content/docs/en/reference/experimental-flags/raw-env-values.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Experimental raw environment variables values -sidebar: - label: Raw environment variables -i18nReady: true ---- - -import Since from '~/components/Since.astro' - -

- -**Type:** `boolean`
-**Default:** `false`
- -

- -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 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.rawEnvValues` flag disables coercion of `import.meta.env` values that are populated from `process.env`, allowing you to use the raw value. - -To disable Astro's coercion on values used through `import.meta.env`, set the `experimental.rawEnvValues` flag to `true` in your Astro configuration: - -```js title="astro.config.mjs" ins={4-6} -import { defineConfig } from "astro/config" - -export default defineConfig({ - experimental: { - rawEnvValues: true, - } -}) -``` - -## Usage - -Enabling this experimental flag will no longer convert string values into booleans or numbers. 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 not coercing `import.meta.env` values by default, but you can opt in to the future behavior early using the `experimental.rawEnvValues` flag and if necessary, [updating your project](#updating-your-project) accordingly. - -### Updating your project - -If you were relying on this 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 need coercion in Astro, we recommend you use [`astro:env`](/en/guides/environment-variables/). diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx new file mode 100644 index 0000000000000..29c4dd13111c4 --- /dev/null +++ b/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' + +

+ +**Type:** `boolean`
+**Default:** `false`
+ +

+ +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`. + +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.rawEnvValues` 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/). From 6c329c40f82f6b7ebbd7ee06be0b904e5916ff30 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Mon, 11 Aug 2025 11:07:21 +0200 Subject: [PATCH 02/10] clarify --- .../en/reference/experimental-flags/static-import-meta-env.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx index 29c4dd13111c4..55d18b556e4b2 100644 --- a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx +++ b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx @@ -16,7 +16,7 @@ import Since from '~/components/Since.astro' 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`. +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. From 422ea9db8a7d2eabd478ae964e76ea86d1537e05 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Mon, 11 Aug 2025 11:21:23 +0200 Subject: [PATCH 03/10] fix: remove translations --- .../experimental-flags/raw-env-values.mdx | 50 ------------------- .../experimental-flags/raw-env-values.mdx | 50 ------------------- 2 files changed, 100 deletions(-) delete mode 100644 src/content/docs/fr/reference/experimental-flags/raw-env-values.mdx delete mode 100644 src/content/docs/ko/reference/experimental-flags/raw-env-values.mdx diff --git a/src/content/docs/fr/reference/experimental-flags/raw-env-values.mdx b/src/content/docs/fr/reference/experimental-flags/raw-env-values.mdx deleted file mode 100644 index 8fc2c6496cd1d..0000000000000 --- a/src/content/docs/fr/reference/experimental-flags/raw-env-values.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Valeurs brutes expérimentales des variables d'environnement -sidebar: - label: Variables d'environnement brutes -i18nReady: true ---- - -import Since from '~/components/Since.astro' - -

- -**Type :** `boolean`
-**Par défaut :** `false`
- -

- -Astro vous permet de configurer un [schéma avec sûreté du typage pour vos variables d'environnement](/fr/guides/environment-variables/#variables-denvironnement-avec-sûreté-du-typage), et convertit les variables importées via `astro:env` dans le type attendu. - -Cependant, Astro convertit également vos variables d'environnement utilisées via `import.meta.env` dans certains cas, ce qui peut empêcher l'accès à certaines valeurs telles que les chaînes de caractères `"true"` (qui est convertie en valeur booléenne) et `"1"` (qui est convertie en nombre). - -L'option `experimental.rawEnvValues` désactive la coercition des valeurs d'`import.meta.env` qui sont renseignées à partir de `process.env`, vous permettant d'utiliser la valeur brute. - -Pour désactiver la coercition d'Astro sur les valeurs utilisées via `import.meta.env`, définissez l'option `experimental.rawEnvValues` sur `true` dans votre configuration Astro : - -```js title="astro.config.mjs" ins={4-6} -import { defineConfig } from "astro/config" - -export default defineConfig({ - experimental: { - rawEnvValues: true, - } -}) -``` - -## Utilisation - -L'activation de cette option expérimentale ne convertira plus les valeurs de chaîne de caractères en booléens ou en nombres. Cela aligne le comportement de `import.meta.env` dans Astro avec celui de [Vite](https://vite.dev/guide/env-and-mode.html#env-variables). - -Dans une future version majeure, Astro passera à la non-contrainte des valeurs d'`import.meta.env` par défaut, mais vous pouvez opter pour le comportement futur plus tôt en utilisant l'option `experimental.rawEnvValues` et si nécessaire, [mettre à jour votre projet](#mise-à-jour-de-votre-projet) en conséquence. - -### Mise à jour de votre projet - -Si vous vous appuyiez sur cette coercition, vous devrez peut-être mettre à jour le code de votre projet pour l'appliquer manuellement : - -```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" -``` - -Si vous avez besoin de coercition dans Astro, nous vous recommandons d'utiliser [`astro:env`](/fr/guides/environment-variables/). diff --git a/src/content/docs/ko/reference/experimental-flags/raw-env-values.mdx b/src/content/docs/ko/reference/experimental-flags/raw-env-values.mdx deleted file mode 100644 index fd7895e7b14b3..0000000000000 --- a/src/content/docs/ko/reference/experimental-flags/raw-env-values.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: 실험적 원시 환경 변수 값 -sidebar: - label: 원시 환경 변수 -i18nReady: true ---- - -import Since from '~/components/Since.astro' - -

- -**타입:** `boolean`
-**기본값:** `false`
- -

- -Astro를 사용하면 [환경 변수에 대한 타입 안전 스키마](/ko/guides/environment-variables/#타입-안전-환경-변수)를 구성할 수 있으며, `astro:env`를 통해 가져온 변수를 예상 타입으로 변환할 수 있습니다. - -그러나 Astro는 경우에 따라 `import.meta.env`를 통해 사용되는 환경 변수도 변환하므로 문자열 `"true"` (부울 값으로 변환) 및 `"1"` (숫자로 변환)과 같은 일부 값에 액세스하지 못할 수도 있습니다. - -`experimental.rawEnvValues` 플래그를 사용하면 `process.env`에서 채워지는 `import.meta.env` 값의 강제 변환을 비활성화하여 원시 값을 사용할 수 있습니다. - -Astro가 `import.meta.env`를 통해 사용되는 값을 강제로 변환하지 못하게 하려면 Astro 구성에서 `experimental.rawEnvValues` 플래그를 `true`로 설정하세요. - -```js title="astro.config.mjs" ins={4-6} -import { defineConfig } from "astro/config" - -export default defineConfig({ - experimental: { - rawEnvValues: true, - } -}) -``` - -## 사용 - -이 실험적 플래그를 활성화하면 더 이상 문자열 값을 부울이나 숫자로 변환하지 않습니다. 이렇게 하면 Astro에서 `import.meta.env`의 동작이 [Vite](https://ko.vite.dev/guide/env-and-mode#env-variables)와 일치하게 됩니다. - -향후 주요 버전에서 Astro가 기본적으로 `import.meta.env` 값을 강제로 변환하지 않도록 전환할 예정이지만, `experimental.rawEnvValues` 플래그를 사용하여 향후 동작을 미리 선택하고 필요한 경우 그에 따라 [프로젝트를 업데이트](#프로젝트-업데이트)할 수 있습니다. - -### 프로젝트 업데이트 - -이 강제 변환에 의존하고 있다면 프로젝트 코드를 업데이트하여 수동으로 적용해야 할 수도 있습니다. - -```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" -``` - -Astro에서 강제 변환이 필요한 경우 [`astro:env`](/ko/guides/environment-variables/)를 사용하는 것이 좋습니다. From 13a7144037b8a18e2d55be403a3d2b07fd48d714 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Mon, 11 Aug 2025 12:05:42 +0200 Subject: [PATCH 04/10] Update src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx Co-authored-by: Armand Philippot --- .../en/reference/experimental-flags/static-import-meta-env.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx index 55d18b556e4b2..61dd4e67bba14 100644 --- a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx +++ b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx @@ -36,7 +36,7 @@ export default defineConfig({ 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.rawEnvValues` flag and if necessary, [updating your project](#updating-your-project) accordingly. +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 From 9320bad0da4b5906cee63fc63b11b16335f9a594 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Tue, 12 Aug 2025 06:42:50 -0300 Subject: [PATCH 05/10] Yan punctuation review Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../reference/experimental-flags/static-import-meta-env.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx index 61dd4e67bba14..34ef27dfc362f 100644 --- a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx +++ b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx @@ -16,7 +16,7 @@ import Since from '~/components/Since.astro' 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). +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. @@ -36,7 +36,7 @@ export default defineConfig({ 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. +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 From dbdb84fef9f8d671b28cd0dfd428461398065c3d Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Tue, 12 Aug 2025 07:42:08 -0300 Subject: [PATCH 06/10] Sarah draft content suggestions after talking with Florian --- .../static-import-meta-env.mdx | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx index 34ef27dfc362f..514685b71758c 100644 --- a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx +++ b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx @@ -14,11 +14,21 @@ import Since from '~/components/Since.astro'

-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. +:::tip[Astro 6.0 preview] +The behavior enabled by this feature will become the default behavior in Astro 6.0. -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). +You may wish to add this flag whenever it is convenient to do so to start enjoying the benefits sooner, and to avoid the need to update your project code for the next major Astro version. +::: -The `experimental.staticImportMetaEnv` flag disables this behavior, ensuring that `import.meta.env` values are always inlined. +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 variable 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: @@ -54,7 +64,7 @@ const enabled: boolean = import.meta.env.DB_PASSWORD const enabled: boolean = process.env.DB_PASSWORD ``` -You may need to update types as well: +You may also need to update types: ```ts title="src/env.d.ts" del={3-4} ins={5,12-16} interface ImportMetaEnv { From e98704651f2a4c5f2d8577f7b1ab1c8416e4b6be Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Tue, 12 Aug 2025 07:46:14 -0300 Subject: [PATCH 07/10] Astro 6.0 tip --- .../en/reference/experimental-flags/static-import-meta-env.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx index 514685b71758c..2e61d840bd143 100644 --- a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx +++ b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx @@ -17,7 +17,7 @@ import Since from '~/components/Since.astro' :::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 to start enjoying the benefits sooner, and to avoid the need to update your project code for the next major Astro version. +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. From c48f0568f1f70272f6bed769c83ba77ab8e25977 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Tue, 12 Aug 2025 09:16:00 -0300 Subject: [PATCH 08/10] Yan final polish Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../reference/experimental-flags/static-import-meta-env.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx index 2e61d840bd143..955051101e190 100644 --- a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx +++ b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx @@ -17,7 +17,7 @@ import Since from '~/components/Since.astro' :::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. +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. @@ -26,7 +26,7 @@ However, you can still access your environment variables through `process.env` a 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 variable 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). +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. From 4ec4e22c2fb6ee984f4dd875c640a01315e84902 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Tue, 12 Aug 2025 14:09:46 -0300 Subject: [PATCH 09/10] semi-colons in code blocks --- .../experimental-flags/static-import-meta-env.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx index 955051101e190..2a9f49f9b35af 100644 --- a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx +++ b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx @@ -53,15 +53,15 @@ In a future major version, Astro will switch to this behavior by default, but yo 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" +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 +const enabled: boolean = import.meta.env.DB_PASSWORD; +const enabled: boolean = process.env.DB_PASSWORD; ``` You may also need to update types: From f54c754449c95fe653c32ecef57704b3ea162327 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Tue, 12 Aug 2025 20:41:54 +0200 Subject: [PATCH 10/10] Update src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- .../reference/experimental-flags/static-import-meta-env.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx index 2a9f49f9b35af..a40a4d0594f92 100644 --- a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx +++ b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx @@ -1,7 +1,7 @@ --- -title: Experimental static import.meta.env +title: Experimental private meta environment variables inlining sidebar: - label: Static import.meta.env + label: Private meta environment variables inlining i18nReady: true ---