Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Valider la configuration et gérer plusieurs environnements (dev, test, prod)

Cette leçon rend la configuration fiable : l'application refuse de démarrer si une variable obligatoire manque ou est invalide, et reçoit des valeurs converties. Trois solutions sont exécutées et comp...

0 chapitres 0 QCM Accès gratuit
Valider la configuration et gérer plusieurs environnements (dev, test, prod)

À propos de ce cours

Cette leçon rend la configuration fiable : l'application refuse de démarrer si une variable obligatoire manque ou est invalide, et reçoit des valeurs converties. Trois solutions sont exécutées et comparées avec @nestjs/config 12, qui accepte désormais tout schéma Standard Schema : Joi, Zod et une fonction validate avec class-validator. La leçon met ensuite en place plusieurs environnements (développement, test, production) avec des fichiers .env par environnement et leur ordre de priorité, l'option ignoreEnvFile pour la production et les scripts npm. Elle se termine par une activité de synthèse sur GitHub.

Objectifs de la leçon

  • Valider les variables d'environnement au démarrage de l'application.
  • Utiliser un schéma Joi ou Zod, ou une fonction validate avec class-validator.
  • Organiser des fichiers .env par environnement et connaître leur priorité.
  • Configurer la production sans fichier .env.
Pourquoi valider au démarrage ?

Sans validation, une variable manquante ou mal écrite (DB_PORT=33O6 avec la lettre O) ne provoque d'erreur qu'au moment où elle est utilisée : parfois des heures après le déploiement, sur une route rarement appelée. Le principe « échouer tôt » (fail fast) : vérifier toute la configuration au démarrage, et refuser de démarrer si elle est incorrecte. L'erreur est alors visible immédiatement, lors du déploiement.

Validation de la configuration et environnements

Une configuration invalide empêche le démarrage ; chaque environnement a ses fichiers.

Solution 1 : un schéma Joi
npm install joi

📄 src/config/environnement.schema.ts

import * as Joi from 'joi';

export const schemaEnvironnement = Joi.object({
  NODE_ENV: Joi.string().valid('development', 'test', 'production').default('development'),
  PORT: Joi.number().port().default(3000),
  DB_HOTE: Joi.string().hostname().required(),
  DB_PORT: Joi.number().port().default(3306),
  DB_UTILISATEUR: Joi.string().required(),
  DB_MOT_DE_PASSE: Joi.string().allow('').required(),
  DB_NOM: Joi.string().required(),
  MAX_STAGIAIRES: Joi.number().integer().min(1).max(200).default(30),
  CLES_API: Joi.string().required(),
});

📄 src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { schemaEnvironnement } from './config/environnement.schema';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validationSchema: schemaEnvironnement,
    }),
  ],
})
export class AppModule {}

Avec un fichier .env correct, puis avec ce fichier incorrect :

📄 .env (correct)

DB_HOTE=localhost
DB_UTILISATEUR=apc_dev
DB_MOT_DE_PASSE=secret_dev
DB_NOM=formation_dev
CLES_API=cle-admin-2026:admin,cle-formateur-2026:formateur

📄 .env (incorrect)

NODE_ENV=prod
PORT=trois-mille
DB_HOTE=localhost
DB_NOM=formation_dev
MAX_STAGIAIRES=500
CLES_API=x

Résultat réellement obtenu :

$ node dist/main.js   (.env correct)
NODE_ENV        = "development" (string)
PORT            = 3000 (number)
DB_PORT         = 3306 (number)
MAX_STAGIAIRES  = 30 (number)

$ node dist/main.js   (.env incorrect)
ERREUR AU DÉMARRAGE : Config validation error: NODE_ENV: "NODE_ENV" must be one of [development, test, production]
PORT: "PORT" must be a number
DB_UTILISATEUR: "DB_UTILISATEUR" is required
DB_MOT_DE_PASSE: "DB_MOT_DE_PASSE" is required
MAX_STAGIAIRES: "MAX_STAGIAIRES" must be less than or equal to 200
  • Avec le bon fichier, PORT, DB_PORT et MAX_STAGIAIRES sont des nombres et ont leurs valeurs par défaut: la validation a aussi converti et complété la configuration. config.get('PORT') renvoie maintenant 3000, pas "3000".
  • Avec le mauvais fichier, l'application ne démarre pas, et toutes les erreurs sont listées d'un coup.

Nouveauté de @nestjs/config 12 : Standard Schema. validationSchema accepte désormais tout schéma qui respecte la norme Standard Schema, comme Joi (version 18), Zod, Valibot ou ArkType. Conséquence pour les tutoriels plus anciens : l'option validationOptions: { abortEarly: false } de Joi n'existe plus (le compilateur la refuse), et toutes les erreurs sont signalées par défaut.

Solution 2 : un schéma Zod

Zod est très utilisé dans l'écosystème TypeScript. Sa particularité : z.coerce.number() indique explicitement la conversion du texte en nombre.

npm install zod

📄 src/config/environnement.schema.ts

import { z } from 'zod';

export const schemaEnvironnement = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DB_HOTE: z.string().min(1),
  DB_NOM: z.string().min(1),
  MAX_STAGIAIRES: z.coerce.number().int().min(1).max(200).default(30),
});

Résultat réellement obtenu :

$ node dist/main.js   (.env correct)
NODE_ENV        = "development" (string)
PORT            = 8080 (number)
MAX_STAGIAIRES  = 30 (number)

$ node dist/main.js   (.env incorrect)
ERREUR AU DÉMARRAGE : Config validation error: NODE_ENV: Invalid option: expected one of "development"|"test"|"production"
PORT: Invalid input: expected number, received NaN
DB_HOTE: Invalid input: expected string, received undefined
MAX_STAGIAIRES: Too big: expected number to be <=200

Le module est identique (validationSchema: schemaEnvironnement) : seule la bibliothèque change. Les messages de Zod sont en anglais ; on peut les personnaliser champ par champ.

Solution 3 : une fonction validate avec class-validator

Vous connaissez class-validator depuis le chapitre 08 : on peut l'utiliser aussi pour la configuration, avec l'option validate, qui reçoit toutes les variables et renvoie la configuration validée ou lève une erreur.

📄 src/config/environnement.validation.ts

import { plainToInstance } from 'class-transformer';
import { IsEnum, IsInt, IsNotEmpty, IsString, Max, Min, validateSync } from 'class-validator';

export enum Environnement {
  Developpement = 'development',
  Test = 'test',
  Production = 'production',
}

class VariablesEnvironnement {
  @IsEnum(Environnement)
  NODE_ENV: Environnement = Environnement.Developpement;

  @IsInt()
  @Min(1)
  @Max(65535)
  PORT: number = 3000;

  @IsString()
  @IsNotEmpty()
  DB_HOTE: string;

  @IsString()
  @IsNotEmpty()
  DB_NOM: string;
}

// Fonction passée à ConfigModule.forRoot({ validate })
export function valider(config: Record<string, unknown>) {
  const valide = plainToInstance(VariablesEnvironnement, config, { enableImplicitConversion: true });
  const erreurs = validateSync(valide, { skipMissingProperties: false });
  if (erreurs.length > 0) {
    const details = erreurs.map((e) => `  - ${e.property} : ${Object.values(e.constraints ?? {}).join(', ')}`).join('\n');
    throw new Error(`Configuration invalide :\n${details}`);
  }
  return valide;            // valeurs converties (PORT est un nombre)
}

📄 src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { valider } from './config/environnement.validation';

@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true, validate: valider })],
})
export class AppModule {}

Résultat réellement obtenu :

$ node dist/main.js   (.env correct)
NODE_ENV        = "development" (string)
PORT            = 8080 (number)
DB_HOTE         = "localhost" (string)

$ node dist/main.js   (.env incorrect)
ERREUR AU DÉMARRAGE : Configuration invalide :
  - NODE_ENV : NODE_ENV must be one of the following values: development, test, production
  - PORT : PORT must not be greater than 65535
  - DB_HOTE : DB_HOTE should not be empty, DB_HOTE must be a string
  - DB_NOM : DB_NOM should not be empty

Ici, enableImplicitConversion convient : les types déclarés (number) guident la conversion du texte. Les valeurs initialisées dans la classe servent de valeurs par défaut.

JoiZodclass-validator
OptionvalidationSchemavalidationSchemavalidate
Conversion des nombresautomatiquez.coerceenableImplicitConversion
Point fortrègles riches (port(), hostname()), historique dans NestJStypage TypeScript déduit du schémamême outil que pour les DTO
Plusieurs environnements

envFilePath accepte un tableau de fichiers. Si une variable est définie dans plusieurs, c'est le premier fichier de la liste qui l'emporte. On construit la liste à partir de NODE_ENV:

📄 src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

const environnement = process.env.NODE_ENV ?? 'development';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      // le PREMIER fichier qui définit une variable l'emporte
      envFilePath: [`.env.${environnement}.local`, `.env.${environnement}`, '.env'],
      ignoreEnvFile: environnement === 'production',   // en production : uniquement les vraies variables
    }),
  ],
})
export class AppModule {}

📄 .env

# valeurs communes à tous les environnements
DB_HOTE=localhost
JOURNAL=log
DB_NOM=formation

📄 .env.development

DB_NOM=formation_dev
JOURNAL=debug

📄 .env.development.local

# réglages personnels du développeur (non versionné)
DB_HOTE=192.168.1.20

📄 .env.test

DB_NOM=formation_test
JOURNAL=error

Résultat réellement obtenu :

$ node dist/main.js
NODE_ENV=(absent) | DB_NOM=formation_dev | DB_HOTE=192.168.1.20 | JOURNAL=debug

$ NODE_ENV=test node dist/main.js
NODE_ENV=test | DB_NOM=formation_test | DB_HOTE=localhost | JOURNAL=error

$ NODE_ENV=production DB_HOTE=db.prod.interne DB_NOM=formation node dist/main.js
NODE_ENV=production | DB_NOM=formation | DB_HOTE=db.prod.interne | JOURNAL=undefined
Lecture des résultats
  • Développement (par défaut) : DB_NOM vient de .env.development, DB_HOTE de .env.development.local (réglage personnel d'un développeur dont la base est sur une autre machine), et ce qui n'est défini nulle part ailleurs vient de .env.
  • Test: base formation_test et journal réduit aux erreurs, sans rien modifier dans le code.
  • Production: aucun fichier n'est lu (JOURNAL est indéfini) ; seules les variables du serveur comptent. Les secrets de production n'existent ainsi dans aucun fichier du projet.

Quels fichiers versionner ? .env.development et .env.test peuvent l'être s'ils ne contiennent aucun secret (valeurs communes à l'équipe). Les fichiers .local et .env ne le sont jamais.

Les scripts npm

📄 package.json (extrait)

{
  "scripts": {
    "start:dev": "nest start --watch",
    "start:test": "cross-env NODE_ENV=test nest start",
    "start:prod": "node dist/main",
    "test:e2e": "cross-env NODE_ENV=test jest --config ./test/jest-e2e.json"
  }
}

cross-env (npm install -D cross-env) permet de définir une variable de la même façon sous Windows, macOS et Linux. En production, NODE_ENV=production et les autres variables sont définis par le serveur : service systemd, PM2, Docker ou panneau d'hébergement (chapitre 20).

Récapitulatif des bonnes pratiques: (1) aucune valeur dépendant de l'environnement dans le code ; (2) toute variable validée au démarrage, avec conversion et valeurs par défaut ; (3) configuration typée par domaine (registerAs) ; (4) .env.example à jour dans le dépôt ; (5) aucun secret dans le dépôt ni dans les journaux ; (6) en production, les variables du serveur uniquement.

Activités

Activité 1 Lire les erreurs

Avec le schéma Joi de la leçon, quelles erreurs produit ce fichier ? NODE_ENV=dev, DB_HOTE=localhost, DB_PORT=33O6, DB_UTILISATEUR=root, DB_MOT_DE_PASSE=, DB_NOM=formation.

Voir le corrigé

Trois erreurs : NODE_ENV doit valoir development, test ou production; DB_PORT doit être un nombre (la lettre O) ; CLES_API est obligatoire. DB_MOT_DE_PASSE vide est accepté grâce à allow(''), et PORT prend la valeur par défaut 3000.

Activité 2 Une règle conditionnelle

En production, DB_MOT_DE_PASSE ne doit pas être vide, alors qu'il peut l'être en développement. Écrivez la règle avec Joi (Joi.when) ou dans une fonction validate.

Voir le corrigé
DB_MOT_DE_PASSE: Joi.string().when('NODE_ENV', {
  is: 'production',
  then: Joi.string().min(12).required(),
  otherwise: Joi.string().allow('').default(''),
}),

Avec class-validator, on peut ajouter dans valider() un test après validateSync: if (valide.NODE_ENV === 'production' && !valide.DB_MOT_DE_PASSE) throw new Error(…).

Activité 3 Un environnement de test

Créez .env.test pour api-formation-securisee avec un port différent et des clés API de test. Ajoutez le script start:test et vérifiez que les clés de développement sont refusées quand l'application tourne en mode test.

Voir le corrigé

.env.test contient par exemple PORT=3100 et CLES_API=cle-test-admin:admin,cle-test-formateur:formateur. Avec envFilePath: [`.env.${env}.local`, `.env.${env}`, '.env'], .env.test passe avant .env: les clés de développement définies dans .env sont remplacées, et une requête avec cle-admin-2026 reçoit 401.

Activité 4 Synthèse : configurer api-formation-securisee

Sur le dépôt GitHub de votre TP 6, dans une branche configuration:

  1. installez @nestjs/config et joi (ou zod) ;
  2. créez src/config/environnement.schema.ts (NODE_ENV, PORT, CORS_ORIGINES, CLES_API, DELAI_MAX_MS) ;
  3. créez app.config.ts et securite.config.ts avec registerAs;
  4. utilisez-les dans main.ts, CleApiGuard et l'intercepteur de délai ;
  5. créez .env.example, .env.development, .env.test et mettez à jour le README (section « Configuration » : tableau des variables, obligatoires ou non, valeurs par défaut) ;
  6. vérifiez qu'une variable manquante empêche le démarrage, faites une pull request vers main, fusionnez et créez l'étiquette v1.1.0.
Voir le corrigé

Points de contrôle : aucune clé API ni valeur d'environnement ne reste dans src/ (git grep cle-admin ne doit rien trouver dans le code) ; git status ne montre jamais .env; l'application démarrée sans CLES_API affiche « Config validation error » et s'arrête ; le README permet à un nouveau développeur de lancer le projet en copiant .env.example. Cette configuration sera directement réutilisée au chapitre 11 pour la connexion à MySQL.

À retenir

  • Valider toute la configuration au démarrage : une configuration invalide empêche de démarrer (fail fast).
  • @nestjs/config 12 : validationSchema accepte un schéma Standard Schema (Joi 18, Zod…) ; ou bien validate().
  • La validation convertit les types et applique les valeurs par défaut : config.get('PORT') devient un nombre.
  • envFilePath en tableau : le premier fichier qui définit une variable l'emporte.
  • Production : ignoreEnvFile et variables du serveur ; aucun secret dans le dépôt.

Cet article vous a-t-il aidé ?