Utiliser des variables d'environnement

:::tip[Vous cherchez astro:env] En savoir plus sur l’API expérimentale astro:env pour des variables d’environnement sûres ! :::

Astro utilise le support intégré de Vite pour les variables d’environnement, qui sont remplacées statiquement au moment de la construction, et vous permet d’utiliser toutes ses méthodes pour travailler avec elles.

Notez que si toutes les variables d’environnement sont disponibles dans le code côté serveur, seules les variables d’environnement préfixées par PUBLIC_ sont disponibles dans le code côté client pour des raisons de sécurité.

.env

SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there

Dans cet exemple, PUBLIC_ANYBODY (accessible via import.meta.env.PUBLIC_ANYBODY) disponible dans le code du serveur ou du client, tandis que SECRET_PASSWORD (accessible via import.meta.env.SECRET_PASSWORD) ne sera disponible que côté serveur.

Attention

Les fichiers .env ne sont pas chargés dans les fichiers de configuration.

Variables d’environnement par défaut

Titre de la section Variables d’environnement par défaut

Astro inclut quelques variables d’environnement par défaut :

• import.meta.env.MODE : Le mode dans lequel tourne votre site. C’est development lorsque vous exécutez astro dev et production lorsque vous exécutez astro build.
• import.meta.env.DEV : true si votre site tourne en développement ; false sinon. Toujours l’opposé de import.meta.env.PROD.
• import.meta.env.BASE_URL : L’URL de base à partir de laquelle votre site est servi. Elle est déterminée par l’option de configuration base.
• import.meta.env.SITE : C’est l’option site spécifiée dans le fichier astro.config de votre projet.
• import.meta.env.ASSETS_PREFIX : Le préfixe pour les liens d’actifs générés par Astro si l’option de configuration build.assetsPrefix est définie. Ceci peut être utilisé pour créer des liens d’actifs non gérés par Astro.

Utilisez-les comme n’importe quelle autre variable d’environnement.

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

Définir des variables d’environnement

Titre de la section Définir des variables d’environnement

Le fichier .env

Titre de la section Le fichier .env

Les variables d’environnement peuvent être chargées à partir des fichiers .env dans le répertoire de votre projet.

Vous pouvez aussi attacher un mode (soit production soit development) au nom du fichier, comme .env.production ou .env.development, ce qui fait que les variables d’environnement ne prennent effet que dans ce mode.

Il suffit de créer un fichier .env dans le répertoire du projet et d’y ajouter quelques variables.

.env

# Ceci ne sera disponible que lorsque vous lancerez le serveur !
DB_PASSWORD="foobar"
# Ceci sera disponible partout !
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"

Pour plus d’informations sur les fichiers .env, voir la documentation de Vite (EN).

Utilisation en CLI

Titre de la section Utilisation en CLI

Vous pouvez également ajouter des variables d’environnement lorsque vous exécutez votre projet :

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

Obtenir des variables d’environnement

Titre de la section Obtenir des variables d’environnement

Les variables d’environnement dans Astro sont accessibles avec import.meta.env, en utilisant la fonctionnalité import.meta ajoutée dans ES2020, au lieu de process.env.

Par exemple, utilisez import.meta.env.PUBLIC_POKEAPI pour obtenir la variable d’environnement PUBLIC_POKEAPI.

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

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

Lorsque vous utilisez SSR, les variables d’environnement peuvent être accédées au moment de l’exécution en fonction de l’adaptateur SSR utilisé. Avec la plupart des adaptateurs, vous pouvez accéder aux variables d’environnement avec process.env, mais certains adaptateurs fonctionnent différemment. Pour l’adaptateur Deno, vous utiliserez Deno.env.get(). Voir comment accéder au runtime Cloudflare pour gérer les variables d’environnement lors de l’utilisation de l’adaptateur Cloudflare. Astro vérifiera d’abord l’environnement du serveur pour les variables, et si elles n’existent pas, Astro les cherchera dans les fichiers .env.

Autocomplétion pour TypeScript

Titre de la section Autocomplétion pour TypeScript

Par défaut, Astro fournit une définition de type pour import.meta.env dans astro/client.d.ts.

Bien que vous puissiez définir plus de variables env personnalisées dans les fichiers .env.[mode], vous voudrez peut-être obtenir l’autocomplétion TypeScript pour les variables env définies par l’utilisateur qui sont préfixées par PUBLIC_.

Pour cela, vous pouvez créer un fichier env.d.ts dans src/ et configurer ImportMetaEnv comme ceci :

src/env.d.ts

interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // plus de variables d'environnement...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}