Variables d'environnement (`.env`)

Configurer votre application pour différents environnements

Une application React a souvent besoin de se comporter différemment ou d'utiliser des valeurs de configuration distinctes selon l'environnement dans lequel elle s'exécute : développement local, tests automatisés, pré-production (staging), ou production finale. Par exemple, l'URL de l'API backend à contacter n'est généralement pas la même en développement et en production. De même, des clés d'API publiques pour des services tiers (comme Google Maps ou Stripe) peuvent différer.

Intégrer ces valeurs directement dans le code source est une mauvaise pratique : cela rend la configuration rigide, expose potentiellement des informations sensibles, et complique le déploiement sur différents environnements. La solution standard pour gérer ces configurations externes est d'utiliser des variables d'environnement.

Les outils de build modernes pour React (Vite, Create React App, Next.js, etc.) intègrent un support pour charger ces variables d'environnement à partir de fichiers spéciaux, le plus souvent nommés avec le préfixe `.env`.

Fonctionnement des fichiers `.env`

Le mécanisme repose sur la création de fichiers texte simple à la racine de votre projet, contenant des paires clé-valeur :

# Exemple de contenu d'un fichier .env
MA_VARIABLE=valeur_par_defaut
REACT_APP_API_URL=http://localhost:5000
VITE_API_KEY=abc123def456
NEXT_PUBLIC_ANALYTICS_ID=UA-XXXX-Y

Les outils de build reconnaissent généralement une hiérarchie de fichiers `.env`, permettant de définir des valeurs par défaut et de les surcharger pour des environnements spécifiques. L'ordre de priorité typique (du moins prioritaire au plus prioritaire) est souvent :

1. .env : Variables par défaut, versionnées dans Git.
2. .env.[mode] : Variables spécifiques à un mode (ex: .env.development, .env.production). Versionnées.
3. .env.local : Variables locales spécifiques à votre machine. Ne doit JAMAIS être versionné dans Git (ajoutez-le à votre .gitignore). Surcharge toutes les autres.
4. .env.[mode].local : Variables locales spécifiques à un mode. Non versionnées, priorité la plus haute.

Par exemple, lors d'un npm run build, l'outil chargera les variables de .env, puis celles de .env.production (qui peuvent surcharger celles de .env), puis celles de .env.local (qui surchargent les précédentes), et enfin celles de .env.production.local (priorité absolue). Les variables d'environnement déjà définies dans le shell système ont souvent une priorité encore plus élevée.

Accès aux variables dans le code Frontend (côté client)

C'est un point crucial pour la sécurité. Pour éviter d'exposer accidentellement des clés secrètes ou des informations sensibles dans le code JavaScript envoyé au navigateur, les outils de build imposent une convention stricte : seules les variables d'environnement commençant par un préfixe spécifique sont accessibles dans le code frontend.

• Create React App : Préfixe REACT_APP_ (ex: REACT_APP_API_URL)
• Vite : Préfixe VITE_ (ex: VITE_API_KEY)
• Next.js : Préfixe NEXT_PUBLIC_ (ex: NEXT_PUBLIC_ANALYTICS_ID)

Toute autre variable définie dans vos fichiers `.env` (sans le préfixe requis) ne sera pas disponible côté client. Vous accédez à ces variables préfixées via l'objet global process.env :

// Exemple dans un composant React (avec Vite)
function ApiConfigDisplay() {
  const apiKey = process.env.VITE_API_KEY; // Accessible car préfixé
  const secret = process.env.DATABASE_PASSWORD; // NON ACCESSIBLE côté client (sera undefined)

  return (
    

      
Clé API publique: {apiKey || 'Non définie'}
      
Secret: {secret || 'Non disponible côté client'}
    
  );
}
export default ApiConfigDisplay;

Important : Incorporation au moment du Build

Il est fondamental de comprendre que les valeurs des variables d'environnement préfixées destinées au frontend sont lues au moment où vous exécutez npm run build et sont directement injectées et remplacées dans le code JavaScript généré. Elles deviennent partie intégrante du bundle statique.

Cela signifie que si vous modifiez un fichier `.env` après avoir exécuté le build, ces changements ne seront pas reflétés dans l'application déployée à moins de relancer un nouveau build. Les variables d'environnement frontend ne sont pas lues dynamiquement depuis le serveur à chaque requête de l'utilisateur.

Cette incorporation au build est la raison pour laquelle il ne faut jamais mettre de secrets dans ces variables préfixées, car ils se retrouveraient en clair dans les fichiers JS servis aux navigateurs.

Variables d'environnement côté serveur (SSR / API Routes)

Lorsque vous utilisez des meta-frameworks comme Next.js ou Remix qui permettent l'exécution de code côté serveur (SSR, SSG, API Routes, loaders, actions), vous pouvez accéder aux variables d'environnement sans le préfixe public. Ces variables restent sécurisées sur le serveur et ne sont jamais envoyées au client.

// Exemple dans une API Route Next.js (pages/api/config.js ou app/api/config/route.ts)
export default function handler(req, res) {
  // Accès à une variable serveur (SANS préfixe NEXT_PUBLIC_)
  const secretKey = process.env.STRIPE_SECRET_KEY; 
  // Accès à une variable publique (AVEC préfixe)
  const publicKey = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY;

  // Utiliser la clé secrète UNIQUEMENT côté serveur
  // ... logique serveur ...

  // Ne retourner que les informations non sensibles au client
  res.status(200).json({ publicKey }); 
}

C'est la méthode correcte pour utiliser des clés API secrètes, des identifiants de base de données, etc. : les utiliser dans la logique exécutée côté serveur et n'exposer au frontend que ce qui est strictement nécessaire et non sensible.

Conclusion : Configurer de manière sûre et flexible

Les variables d'environnement, chargées via les fichiers `.env`, sont un mécanisme standard et essentiel pour gérer la configuration de vos applications React dans différents environnements. Elles offrent flexibilité et permettent de séparer la configuration du code.

La distinction clé à retenir est celle entre les variables destinées au frontend (qui doivent avoir un préfixe spécifique et sont injectées au build time, donc non sécurisées pour les secrets) et les variables destinées uniquement au serveur (sans préfixe, accessibles seulement dans le code exécuté côté serveur). Utiliser correctement cette distinction est fondamental pour la sécurité et la bonne configuration de votre application React en production.