Uso de variables de entorno

Astro te da acceso al soporte integrado de variables de entorno de Vite e incluye algunas variables de entorno por defecto para tu proyecto que te permiten acceder a valores de configuración de tu proyecto actual (por ejemplo, site, base), saber si tu proyecto se está ejecutando en desarrollo o producción, y más.

Astro también proporciona una forma de usar y organizar tus variables de entorno con seguridad de tipos. Está disponible para su uso dentro del contexto de Astro (por ejemplo, componentes de Astro, rutas y endpoints, componentes de frameworks de UI, middleware), y se gestiona con un esquema en tu configuración de Astro.

Soporte integrado de Vite

Astro utiliza el soporte integrado de Vite para variables de entorno, las cuales se reemplazan estáticamente en tiempo de construcción, y te permite usar cualquiera de sus métodos para trabajar con ellas.

Ten en cuenta que mientras todas las variables de entorno están disponibles en el código del lado del servidor, solo las variables de entorno con el prefijo PUBLIC_ están disponibles en el código del lado del cliente por motivos de seguridad.

.env

SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there

En este ejemplo, PUBLIC_ANYBODY (accesible a través de import.meta.env.PUBLIC_ANYBODY) estará disponible en el código del servidor o del cliente, mientras que SECRET_PASSWORD (accesible a través de import.meta.env.SECRET_PASSWORD) será de uso exclusivo en el lado del servidor.

Precaución

Los archivos .env no se cargan dentro de los archivos de configuración.

IntelliSense para TypeScript

Por defecto, Astro proporciona una definición de tipo para import.meta.env en astro/client.d.ts.

Aunque puedes definir más variables de entorno personalizadas en archivos .env.[mode], es posible que desees obtener IntelliSense de TypeScript para las variables de entorno definidas por el usuario que tienen el prefijo PUBLIC_.

Para lograr esto, puedes crear un archivo env.d.ts en src/ para extender los tipos globales y configurar ImportMetaEnv de esta manera:

src/env.d.ts

interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // more env variables...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Variables de entorno por defecto

Astro incluye algunas variables de entorno de fábrica:

• import.meta.env.MODE: El modo en el que se ejecuta tu sitio. Esto es development al ejecutar astro dev y production al ejecutar astro build.
• import.meta.env.PROD: true si tu sitio se ejecuta en producción; false de lo contrario.
• import.meta.env.DEV: true si tu sitio se ejecuta en desarrollo; false de lo contrario. Siempre lo opuesto a import.meta.env.PROD.
• import.meta.env.BASE_URL: La URL base desde la cual se sirve tu sitio. Esto se determina mediante la opción de configuración base.
• import.meta.env.SITE: Esto se establece en la opción site especificada en tu archivo astro.config.

Úsalas como cualquier otra variable de entorno.

const isProd = import.meta.env.PROD;
const isDev = import.meta.env.DEV;

Configurar variables de entorno

Archivos .env

Las variables de entorno se pueden cargar desde archivos .env en el directorio de tu proyecto.

Simplemente crea un archivo .env en el directorio del proyecto y añádele algunas variables.

.env

# This will only be available when run on the server!
DB_PASSWORD="foobar"

# This will be available everywhere!
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"

También puedes añadir .production, .development o un nombre de modo personalizado al propio nombre del archivo (por ejemplo, .env.testing, .env.staging). Esto te permite utilizar diferentes conjuntos de variables de entorno en diferentes momentos.

Los comandos astro dev y astro build tienen como valor predeterminado los modos "development" y "production", respectivamente. Puedes ejecutar estos comandos con la bandera --mode para pasar un valor diferente de mode y cargar el archivo .env correspondiente.

Esto te permite ejecutar el servidor de desarrollo o construir tu sitio conectándote a diferentes APIs:

npm

# Run the dev server connected to a "staging" API
npm run astro dev -- --mode staging

# Build a site that connects to a "production" API with additional debug information
npm run astro build -- --devOutput

# Build a site that connects to a "testing" API
npm run astro build -- --mode testing

pnpm

# Run the dev server connected to a "staging" API
pnpm astro dev --mode staging

# Build a site that connects to a "production" API with additional debug information
pnpm astro build --devOutput

# Build a site that connects to a "testing" API
pnpm astro build --mode testing

Yarn

# Run the dev server connected to a "staging" API
yarn astro dev --mode staging

# Build a site that connects to a "production" API with additional debug information
yarn astro build --devOutput

# Build a site that connects to a "testing" API
yarn astro build --mode testing

Para saber más sobre los archivos .env, consulta la documentación de Vite.

En el archivo de configuración de Astro

Astro evalúa los archivos de configuración antes de cargar tus otros archivos. Esto significa que no puedes usar import.meta.env en astro.config.mjs para acceder a las variables de entorno que se configuraron en los archivos .env.

Puedes usar process.env en un archivo de configuración para acceder a otras variables de entorno, como aquellas configuradas por la CLI.

También puedes usar el ayudante loadEnv de Vite para cargar manualmente los archivos .env.

astro.config.mjs

import { loadEnv } from "vite";

const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

Nota

pnpm no te permite importar módulos que no estén instalados directamente en tu proyecto. Si estás utilizando pnpm, necesitarás instalar vite para usar el ayudante loadEnv.

pnpm add -D vite

Usando la CLI

También puedes añadir variables de entorno al ejecutar tu proyecto:

npm

PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev

pnpm

PUBLIC_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev

Yarn

PUBLIC_POKEAPI=https://pokeapi.co/api/v2 yarn run dev

Obtener variables de entorno

A las variables de entorno en Astro se accede con import.meta.env, utilizando la característica import.meta añadida en ES2020, en lugar de process.env.

Por ejemplo, usa import.meta.env.PUBLIC_POKEAPI para obtener la variable de entorno PUBLIC_POKEAPI.

// When import.meta.env.SSR === true
const data = await db(import.meta.env.DB_PASSWORD);

// When import.meta.env.SSR === false
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);

Cuando utilizas SSR, se puede acceder a las variables de entorno en tiempo de ejecución en función del adaptador de SSR que estés utilizando. Con la mayoría de los adaptadores puedes acceder a las variables de entorno con process.env, pero algunos adaptadores funcionan de manera diferente. Para el adaptador de Deno, utilizarás Deno.env.get(). Consulta cómo acceder al entorno de ejecución de Cloudflare para manejar variables de entorno cuando utilizas el adaptador de Cloudflare. Astro comprobará primero el entorno del servidor en busca de variables, y si no existen, Astro las buscará en los archivos .env.

Variables de entorno con seguridad de tipos

La API astro:env te permite configurar un esquema con seguridad de tipos para las variables de entorno que has configurado. Esto te permite indicar si deben estar disponibles en el servidor o en el cliente, así como definir su tipo de datos y propiedades adicionales.

¿Estás desarrollando un adaptador? Consulta cómo hacer que un adaptador sea compatible con astro:env.

Uso básico

Define tu esquema

Para configurar un esquema, añade la opción env.schema a tu configuración de Astro:

astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      // ...
    }
  }
})

Luego puedes registrar variables como cadena de texto, número, enumeración o booleano utilizando el ayudante envField. Define el tipo de variable de entorno proporcionando un context ("client" o "server") and access ("secret" o "public") para cada variable, y pasa cualquier propiedad adicional como optional o default en un objeto:

astro.config.mjs

import { defineConfig, envField } from "astro/config";

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

Los tipos se generarán automáticamente para ti al ejecutar astro dev o astro build, pero puedes ejecutar astro sync para generar únicamente los tipos.

Usa variables de tu esquema

Importa y usa tus variables definidas desde el módulo /client o /server correspondiente:

---
import { API_URL } from "astro:env/client";
import { API_SECRET_TOKEN } from "astro:env/server";

const data = await fetch(`${API_URL}/users`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_SECRET_TOKEN}`
  },
})
---

<script>
  import { API_URL } from "astro:env/client";

  fetch(`${API_URL}/ping`)
</script>

Tipos de variables

Hay tres tipos de variables de entorno, determinados por la combinación de los ajustes de context ("client" o "server") y access ("secret" o "public") definidos en tu esquema:

• Variables de cliente públicas: Estas variables terminan tanto en tu bundle final de cliente como de servidor, y se puede acceder a ellas tanto desde el cliente como desde el servidor a través del módulo astro:env/client:

  import { API_URL } from "astro:env/client";

• Variables de servidor públicas: Estas variables terminan en tu bundle de servidor final y se puede acceder a ellas en el servidor a través del módulo astro:env/server:

  import { PORT } from "astro:env/server";

• Variables de servidor secretas: Estas variables no forman parte de tu bundle final y se puede acceder a ellas en el servidor a través del módulo astro:env/server:

  import { API_SECRET } from "astro:env/server";

  Por defecto, todos los secretos se validan cada vez que se importa algo del módulo astro:env/server. Esto significa que los secretos pueden ser validados incluso cuando no se importan. Es posible que necesites pasar variables de entorno ficticias para satisfacer esta validación durante la construcción.

  También puedes habilitar la validación de secretos al inicio configurando validateSecrets: true.

Nota

Las variables de cliente secretas no son compatibles porque no existe una forma segura de enviar esta información al cliente. Por lo tanto, no es posible configurar tanto context: "client" como access: "secret" en tu esquema.

Tipos de datos

Actualmente se admiten cuatro tipos de datos: cadenas de texto, números, enumeraciones y booleanos:

import { envField } from "astro/config";

envField.string({
   // context & access
   optional: true,
   default: "foo",
})

envField.number({
   // context & access
   optional: true,
   default: 15,
})

envField.boolean({
   // context & access
   optional: true,
   default: true,
})

envField.enum({
   // context & access
   values: ["foo", "bar", "baz"],
   optional: true,
   default: "baz",
})

Para obtener una lista completa de los campos de validación, consulta la referencia de la API de envField.

Obtener secretos dinámicamente

A pesar de definir tu esquema, es posible que desees recuperar el valor bruto de un secreto específico o recuperar secretos no definidos en tu esquema. En este caso, puedes utilizar getSecret() exportado de astro:env/server:

import {
   FOO, // boolean
   getSecret
} from "astro:env/server";

getSecret("FOO"); // string | undefined

Obtén más información en la referencia de la API.

Limitaciones

astro:env es un módulo virtual, lo que significa que solo se puede utilizar dentro del contexto de Astro. Por ejemplo, puedes utilizarlo en:

• Middlewares
• Rutas y endpoints de Astro
• Componentes de Astro
• Componentes de frameworks
• Módulos

No puedes usarlo en lo siguiente y tendrás que recurrir a process.env:

• astro.config.mjs
• Scripts