Aller au contenu

Variables d'environnement

Vue d'ensemble

Nx gère automatiquement le chargement des fichiers d'environnement lors de l'exécution d'un projet.

Selon le projet, le target exécuté et la configuration utilisée, Nx sélectionne automatiquement le ou les fichiers .env les plus adaptés.

L'objectif est de permettre à chaque projet de posséder sa propre configuration tout en évitant la duplication des variables d'environnement.

À retenir

Le nom du fichier d'environnement dépend directement du target et de la configuration exécutés.

Pourquoi plusieurs fichiers .env ?

L'utilisation de plusieurs fichiers d'environnement permet notamment de :

  • Séparer les environnements de développement, de test et de production.
  • Éviter les gros fichiers .env contenant toutes les variables du projet.
  • Isoler la configuration propre à chaque application ou service.
  • Faciliter la maintenance et la lecture des variables d'environnement.

Convention de nommage

Chaque projet possède un fichier project.json décrivant les targets disponibles.

Exemple :

{
  "targets": {
    "serve": {},
    "build": {},
    "test": {}
  }
}

Le nom du fichier .env est construit à partir du target exécuté.

Target Fichier
serve .serve.env
build .build.env
test .test.env

Lorsqu'une configuration est utilisée, celle-ci est ajoutée au nom du fichier.

Commande Fichier recherché
serve:development .serve.development.env
serve:production .serve.production.env
build:production .build.production.env
test:ci .test.ci.env

Exemple concret

Si la commande suivante est exécutée :

pnpm nx run @feelbat/auth:serve:development

Nx sait que :

  • le projet est @feelbat/auth
  • le target exécuté est serve
  • la configuration est development

Il recherchera donc en priorité les fichiers correspondant à ce contexte.

Le schéma suivant résume le mécanisme de résolution :

flowchart TD
    command["pnpm nx run @feelbat/auth:serve:development"]

    command --> project["Projet : @feelbat/auth"]
    command --> target["Target : serve"]
    command --> config["Configuration : development"]

    project --> resolution["Résolution des fichiers .env"]
    target --> resolution
    config --> resolution

    resolution --> specific[".serve.development.env"]
    resolution --> targetEnv[".serve.env"]
    resolution --> defaultEnv[".env"]

Où placer les fichiers .env ?

Les fichiers d'environnement doivent être placés directement dans le dossier du projet concerné.

Exemple :

apps/api/auth/
├── .serve.env
├── .serve.development.env
├── .build.env
└── .test.env

Tip

Gardez les variables d'environnement au plus près du projet qui les utilise. Évitez les fichiers globaux lorsqu'ils ne sont pas nécessaires.

Bonnes pratiques

  • Ne jamais versionner de secrets réels.
  • Fournir un .env.example lorsqu'un projet nécessite une configuration spécifique.
  • Supprimer les variables devenues inutiles.
  • Donner des noms explicites aux variables.
  • Documenter les variables importantes lorsqu'elles ne sont pas évidentes.

Exemple :

DATABASE_URL=
KAFKA_BROKERS=
JWT_SECRET=

Warning

Les fichiers contenant des secrets ou des identifiants de production ne doivent jamais être commit dans le dépôt Git.

Résolution des problèmes

Si une variable d'environnement ne semble pas être chargée :

  1. Vérifiez le nom du target exécuté.
  2. Vérifiez la configuration utilisée (development, production, etc.).
  3. Vérifiez le nom du fichier .env.
  4. Vérifiez que le fichier est placé dans le bon projet.
  5. Vérifiez le project.json afin de confirmer le nom exact du target.

Pour afficher les projets disponibles :

pnpm nx show projects

Pour consulter la configuration d'un projet :

pnpm nx show project @feelbat/auth

À éviter

  • Utiliser un unique fichier .env pour tout le monorepo.
  • Dupliquer les mêmes variables dans plusieurs projets sans raison.
  • Utiliser des secrets de production en local.
  • Renommer un target sans mettre à jour les fichiers .env associés.