astro/.changeset/poor-berries-occur.md

astro
minor

Adds experimental support for the astro:env API.

The astro:env API lets you configure a type-safe schema for your environment variables, and indicate whether they should be available on the server or the client. Import and use your defined variables from the appropriate /client or /server module:

---
import { PUBLIC_APP_ID } from "astro:env/client"
import { PUBLIC_API_URL, getSecret } from "astro:env/server"
const API_TOKEN = getSecret("API_TOKEN")

const data = await fetch(`${PUBLIC_API_URL}/users`, {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		"Authorization": `Bearer ${API_TOKEN}`
	},
	body: JSON.stringify({ appId: PUBLIC_APP_ID })
})
---

To define the data type and properties of your environment variables, declare a schema in your Astro config in experimental.env.schema. The envField helper allows you define your variable as a string, number, or boolean and pass properties in an object:

// astro.config.mjs
import { defineConfig, envField } from "astro/config"

export default defineConfig({
    experimental: {
        env: {
            schema: {
                PUBLIC_API_URL: envField.string({ context: "client", access: "public", optional: true }),
                PUBLIC_PORT: envField.number({ context: "server", access: "public", default: 4321 }),
                API_SECRET: envField.string({ context: "server", access: "secret" }),
            }
        }
    }
})

There are three kinds of environment variables, determined by the combination of context (client or server) and access (private or public) settings defined in your env.schema:

• Public client variables: These variables end up in both your final client and server bundles, and can be accessed from both client and server through the astro:env/client module:

  import { PUBLIC_API_URL } from "astro:env/client"
  

• Public server variables: These variables end up in your final server bundle and can be accessed on the server through the astro:env/server module:

  import { PUBLIC_PORT } from "astro:env/server"
  

• Secret server variables: These variables are not part of your final bundle and can be accessed on the server through the getSecret() helper function available from the astro:env/server module:

  import { getSecret } from "astro:env/server"
  
  const API_SECRET = getSecret("API_SECRET") // typed
  const SECRET_NOT_IN_SCHEMA = getSecret("SECRET_NOT_IN_SCHEMA") // string | undefined
  

Note: Secret client variables are not supported because there is no safe way to send this data to the client. Therefore, it is not possible to configure both context: "client" and access: "secret" in your schema.

To learn more, check out the documentation.