Experimental private meta environment variables inlining

Type: boolean
Default: false

أُضيفت في: astro@5.13.0 جديد

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, 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 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:

astro.config.mjs

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.

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 accordingly.

Updating your project

If you were relying on coercion, you may need to update your project code to apply it manually:

src/components/MyComponent.astro

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:

src/components/MyComponent.astro

const enabled: boolean = import.meta.env.DB_PASSWORD;
const enabled: boolean = process.env.DB_PASSWORD;

You may also need to update types:

src/env.d.ts

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.