Usando variables de entorno

Astro te da acceso a la soporte integrada de Vite con variables de entorno e incluye algunas variables de entorno predeterminadas para tu proyecto que te permiten acceder a valores de configuración de tu proyecto actual (por ejemplo, site, base), ya sea que tu proyecto se esté ejecutando en desarrollo o en producción, y más.

Astro también ofrece 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 interfaz de usuario, middleware) y se gestiona mediante un esquema en tu configuración de Astro).

Soporte integrada de Vite

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

Ten en cuenta que todas las variables de entorno estarán disponibles en el servidor, mientras que solo las variables de entorno con el prefijo PUBLIC_ estarán disponibles en el cliente por motivos de seguridad.

.env

SECRET_PASSWORD=contraseña123
PUBLIC_ANYBODY=ahí

En este ejemplo, PUBLIC_ANYBODY (accesible mediante import.meta.env.PUBLIC_ANYBODY) estará disponible tanto en el servidor como el cliente, mientras que SECRET_PASSWORD (accesible mediante import.meta.env.SECRET_PASSWORD) estará disponible solo en el servidor.

Precaución

Los archivos .env no son cargados dentro de archivos de configuración.

IntelliSense para TypeScript

De forma predeterminada, Astro proporciona una definición de tipos para import.meta.env en astro/client.d.ts.

Aunque puedes definir más variables de entorno personalizadas en archivos .env.[mode], quizá quieras obtener IntelliSense de TypeScript para las variables de entorno definidas por el usuario que estén prefijadas con PUBLIC_.

Para lograrlo, puedes crear un archivo env.d.ts en src/ y configurar ImportMetaEnv de esta manera:

src/env.d.ts

interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // más variables de entorno...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Variables de entorno predeterminadas

Astro incluye algunas variables de entorno por defecto:

• import.meta.env.MODE: El modo en el que se ejecuta tu proyecto. Esto es development al ejecutar astro dev y production al ejecutar astro build.
• import.meta.env.PROD: true si tu proyecto se está ejecutando en producción; false en caso contrario.
• import.meta.env.DEV: true si tu proyecto se está ejecutando en desarrollo; false en caso contrario. Siempre lo contrario de import.meta.env.PROD.
• import.meta.env.BASE_URL: La URL base desde la que se sirve tu proyecto. Esto está determinado por la opción de configuración base.
• import.meta.env.SITE: Esto se establece en la opción site especificada en astro.config de tu proyecto.
• import.meta.env.ASSETS_PREFIX: El prefijo para los enlaces de activos generados por Astro si se establece la opción de configuración build.assetsPrefix. Esto se puede usar para crear enlaces de activos no manejados por Astro.

Úsalas como cualquier otra variable de entorno.

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

Configurando variables de entorno

Archivos .env

Las variables de entorno se pueden cargar desde los archivos .env en la raíz de tu proyecto.

Simplemente crea un archivo .env en la raíz de tu proyecto y agrega algunas variables.

.env

# ¡Esto solo estará disponible cuando se ejecute en el servidor!
DB_PASSWORD="foobar"

# ¡Estará disponible en todas partes!
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 usar diferentes conjuntos de variables de entorno en distintos momentos.

Los comandos astro dev y astro build usan por defecto los modos "development" y "production", respectivamente. Puedes ejecutar estos comandos con la opción --mode para pasar un valor diferente para mode y cargar el archivo .env correspondiente.

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

npm

# Ejecutar el servidor de desarrollo conectado a una API de “staging”
npm run astro dev -- --mode staging

# Compilar un sitio que se conecta a una API de "producción" con información de depuración adicional
npm run astro build -- --devOutput

# Compilar un sitio que se conecta a una API de "pruebas"
npm run astro build -- --mode testing

pnpm

# Ejecutar el servidor de desarrollo conectado a una API de “staging”
pnpm astro dev --mode staging

 # Compilar un sitio que se conecta a una API de "producción" con información de depuración adicional
pnpm astro build --devOutput

# Compilar un sitio que se conecta a una API de "pruebas"
pnpm astro build --mode testing

Yarn

# Ejecutar el servidor de desarrollo conectado a una API de “staging”
yarn astro dev --mode staging

# Compilar un sitio que se conecta a una API de "producción" con información de depuración adicional
yarn astro build --devOutput

# Compilar un sitio que se conecta a una API de "pruebas"
yarn astro build --mode testing

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

In the Astro config file

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 variables de entorno que se hayan definido en archivos .env.

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

También puedes usar el helper 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 usando pnpm, necesitarás instalar vite para poder usar el helper loadEnv.

pnpm add -D vite

Usando la CLI

También puedes agregar variables de entorno a medida que ejecuta su 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

Obteniendo variables de entorno

En Astro se accede a las variables de entorno 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.

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

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

Cuando se utiliza SSR, se puede acceder a las variables de entorno en tiempo de ejecución en función del adaptador SSR que se esté utilizando. Con la mayoría de los adaptadores puedes acceder a las variables de entorno con process.env, pero algunos adaptadores funcionan de forma diferente. Para el adaptador Deno, utilizará Deno.env.get(). Mira cómo acceder al runtime de Cloudflare para manejar las variables de entorno cuando utilices 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 hayas establecido. Esto te permite indicar si deben estar disponibles en el servidor o en el cliente, así como definir su tipo de dato y propiedades adicionales.

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

Uso básico

Definir 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, número, enumeración o booleano usando el helper envField. Define el tipo de variable de entorno proporcionando un context ("client" o "server") y un 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 al ejecutar astro dev o astro build, pero puedes ejecutar astro sync para generar únicamente los tipos.

Usar variables de tu esquema

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

---
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 las opciones context ("client" o "server") y access ("secret" o "public") definidas en tu esquema:

• Variables públicas de cliente: Estas variables terminan tanto en el bundle final del cliente como en el del servidor, y pueden accederse desde ambos (cliente y servidor) a través del módulo astro:env/client:

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

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

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

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

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

De forma predeterminada, los secretos solo se validan en tiempo de ejecución. Puedes habilitar la validación de variables privadas al inicio configurando validateSecrets: true.

Nota

Las variables secretas de cliente no son compatibles porque no existe una forma segura de enviar estos datos al cliente. Por lo tanto, no es posible configurar simultáneamente context: "client" y access: "secret" en tu esquema.

Tipos de datos

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

import { envField } from "astro/config";

envField.string({
   // contexto y acceso
   optional: true,
   default: "foo",
})

envField.number({
   // contexto y acceso
   optional: true,
   default: 15,
})

envField.boolean({
   // contexto y acceso
   optional: true,
   default: true,
})

envField.enum({
   // contexto y acceso
   values: ["foo", "bar", "baz"],
   optional: true,
   default: "baz",
})

Para ver la lista completa de campos de validación, consulta la referencia de la API envField.

Recuperar secretos de forma dinámica

Aunque definas tu esquema, puede que quieras obtener el valor en bruto de un secreto específico o recuperar secretos que no estén definidos en tu esquema. En este caso, puedes usar getSecret() exportado desde 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 (EN).

Limitaciones

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

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

No puedes usarlo en los siguientes casos y tendrás que recurrir a process.env:

• astro.config.mjs
• Scripts