À propos de ce cours
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.
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_PORTetMAX_STAGIAIRESsont des nombres et ont leurs valeurs par défaut: la validation a aussi converti et complété la configuration.config.get('PORT')renvoie maintenant3000, 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.
| Joi | Zod | class-validator | |
|---|---|---|---|
| Option | validationSchema | validationSchema | validate |
| Conversion des nombres | automatique | z.coerce | enableImplicitConversion |
| Point fort | règles riches (port(), hostname()), historique dans NestJS | typage TypeScript déduit du schéma | mê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_NOMvient de.env.development,DB_HOTEde.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_testet journal réduit aux erreurs, sans rien modifier dans le code. - Production: aucun fichier n'est lu (
JOURNALest 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:
- installez
@nestjs/configetjoi(ouzod) ; - créez
src/config/environnement.schema.ts(NODE_ENV, PORT, CORS_ORIGINES, CLES_API, DELAI_MAX_MS) ; - créez
app.config.tsetsecurite.config.tsavecregisterAs; - utilisez-les dans
main.ts,CleApiGuardet l'intercepteur de délai ; - créez
.env.example,.env.development,.env.testet mettez à jour le README (section « Configuration » : tableau des variables, obligatoires ou non, valeurs par défaut) ; - vérifiez qu'une variable manquante empêche le démarrage, faites une pull request vers
main, fusionnez et créez l'étiquettev1.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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !