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

Le module @nestjs/config (ConfigModule, ConfigService)

Cette leçon présente le module officiel @nestjs/config, qui charge le fichier .env et met la configuration à disposition de toute l'application par injection. Elle détaille les options de ConfigModule...

0 chapitres 0 QCM Accès gratuit
Le module @nestjs/config (ConfigModule, ConfigService)

À propos de ce cours

Cette leçon présente le module officiel @nestjs/config, qui charge le fichier .env et met la configuration à disposition de toute l'application par injection. Elle détaille les options de ConfigModule.forRoot (isGlobal, envFilePath, expandVariables, cache), les méthodes get avec valeur par défaut et getOrThrow, et montre par l'exécution que get ne convertit pas la valeur. Elle présente ensuite la configuration typée par espaces de noms avec registerAs et ConfigType, puis l'utilisation de la configuration dans main.ts et dans un provider useFactory, préparation directe du chapitre 11. Activités corrigées.

Objectifs de la leçon

  • Installer et configurer ConfigModule.
  • Lire la configuration avec ConfigService.
  • Organiser une configuration typée avec registerAs.
  • Utiliser la configuration dans main.ts et dans une fabrique de provider.
Installation
npm install @nestjs/config

Version: la version actuelle de @nestjs/config est la 12 (elle est passée directement de la 4 à la 12 pour s'aligner sur NestJS). Les exemples de cette leçon et de la suivante ont été exécutés avec la version 12.1. Ses différences avec les tutoriels plus anciens concernent surtout la validation (leçon 10.3).

Fonctionnement de @nestjs/config

ConfigModule charge les sources une fois ; ConfigService les fournit partout.

ConfigModule.forRoot et ConfigService

📄 .env

PORT=3000
NODE_ENV=development
APP_NOM=api-formation
APP_URL=http://localhost:${PORT}
DB_HOTE=localhost
DB_PORT=3306
DB_UTILISATEUR=apc_dev
DB_MOT_DE_PASSE=secret_dev
DB_NOM=formation_dev
MAX_STAGIAIRES=30

📄 src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { InfoService } from './info.service';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,              // ConfigService disponible dans tous les modules
      envFilePath: '.env',         // valeur par défaut
      expandVariables: true,       // autorise ${AUTRE_VARIABLE}
      cache: true,                 // garde les valeurs en mémoire (plus rapide)
    }),
  ],
  providers: [InfoService],
})
export class AppModule {}

📄 src/info.service.ts

import { Injectable, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class InfoService implements OnModuleInit {
  constructor(private readonly config: ConfigService) {}

  onModuleInit() {
    // 1. lecture simple
    console.log('APP_NOM         :', this.config.get('APP_NOM'));

    // 2. le paramètre de type NE CONVERTIT PAS
    const port = this.config.get<number>('PORT');
    console.log('PORT            :', JSON.stringify(port), '→ typeof', typeof port);

    // 3. valeur par défaut si la variable est absente
    console.log('LANGUE          :', this.config.get('LANGUE', 'fr'));

    // 4. variable obligatoire
    try {
      this.config.getOrThrow('CLE_API_SMS');
    } catch (e) {
      console.log('getOrThrow      :', (e as Error).message);
    }

    // 5. expansion ${PORT} (option expandVariables)
    console.log('APP_URL         :', this.config.get('APP_URL'));

    // 6. une variable réelle de la machine est aussi lisible
    console.log('HOME défini ?   :', this.config.get('HOME') !== undefined);
  }
}

Résultat réellement obtenu :

$ node dist/main.js
APP_NOM         : api-formation
PORT            : "3000" → typeof string
LANGUE          : fr
getOrThrow      : Configuration key "CLE_API_SMS" does not exist
APP_URL         : http://localhost:3000
HOME défini ?   : true

$ PORT=4000 node dist/main.js
APP_NOM         : api-formation
PORT            : "4000" → typeof string
LANGUE          : fr
getOrThrow      : Configuration key "CLE_API_SMS" does not exist
APP_URL         : http://localhost:4000
HOME défini ?   : true
Ce qu'il faut observer
  • isGlobal: true: sans cette option, il faudrait importer ConfigModule dans chaque module qui utilise ConfigService. On l'active presque toujours.
  • get<number>('PORT') renvoie la chaîne "3000": le paramètre de type ne sert qu'au compilateur, aucune conversion n'a lieu. C'est le piège le plus fréquent avec ce module. Solutions : convertir dans registerAs (ci-dessous) ou valider avec conversion (leçon 10.3).
  • get('LANGUE', 'fr'): le second argument est la valeur par défaut.
  • getOrThrow() lève une erreur si la variable n'existe pas : à utiliser pour les valeurs indispensables.
  • expandVariables permet d'écrire APP_URL=http://localhost:${PORT}: la seconde exécution montre que l'expansion utilise la valeur réelle (4000).
  • Les variables du système (ici HOME) sont aussi accessibles, et une variable définie au lancement l'emporte sur le fichier.
Option de forRootRôle
isGlobalConfigService disponible dans tous les modules
envFilePathchemin du fichier (ou tableau de chemins, leçon 10.3) ; défaut : .env
ignoreEnvFilene lit aucun fichier (production)
expandVariablesactive ${VARIABLE} dans le fichier
cachegarde les valeurs lues en mémoire
loadfichiers de configuration typés (registerAs)
validationSchema / validatevalidation au démarrage (leçon 10.3)
overridele fichier écrase les variables existantes (rarement souhaitable)
Une configuration typée avec registerAs

Lire des chaînes avec des noms de variables partout dans le code est fragile (faute de frappe, conversion oubliée). On regroupe la configuration par domaine dans des fichiers dédiés, qui lisent et convertissent une seule fois:

📄 src/config/app.config.ts

import { registerAs } from '@nestjs/config';

export default registerAs('app', () => ({
  nom: process.env.APP_NOM ?? 'api',
  port: Number.parseInt(process.env.PORT ?? '3000', 10),      // ✓ converti ici, une fois pour toutes
  environnement: process.env.NODE_ENV ?? 'development',
  maxStagiaires: Number.parseInt(process.env.MAX_STAGIAIRES ?? '30', 10),
}));

📄 src/config/database.config.ts

import { registerAs } from '@nestjs/config';

export default registerAs('database', () => ({
  hote: process.env.DB_HOTE ?? 'localhost',
  port: Number.parseInt(process.env.DB_PORT ?? '3306', 10),
  utilisateur: process.env.DB_UTILISATEUR ?? 'root',
  motDePasse: process.env.DB_MOT_DE_PASSE ?? '',
  nom: process.env.DB_NOM ?? 'formation',
}));

📄 src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import appConfig from './config/app.config';
import databaseConfig from './config/database.config';
import { StagiairesService } from './stagiaires.service';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [appConfig, databaseConfig],   // fichiers de configuration typés
    }),
  ],
  providers: [StagiairesService],
})
export class AppModule {}

Deux façons de les utiliser :

📄 src/stagiaires.service.ts

import { Inject, Injectable } from '@nestjs/common';
import { ConfigService, type ConfigType } from '@nestjs/config';
import appConfig from './config/app.config';
import databaseConfig from './config/database.config';

@Injectable()
export class StagiairesService {
  constructor(
    @Inject(appConfig.KEY) private readonly app: ConfigType<typeof appConfig>,   // objet typé
    private readonly config: ConfigService,
  ) {}

  afficher() {
    console.log('app (injecté)        :', this.app);
    console.log('typeof app.port      :', typeof this.app.port);
    console.log('limite atteinte à 31 ?', 31 > this.app.maxStagiaires);
    // Autre accès : chemin pointé dans l'espace de noms
    console.log("get('database.hote') :", this.config.get('database.hote'));
    console.log("get('database')      :", this.config.get('database'));
  }
}

Résultat réellement obtenu :

$ node dist/main.js
app (injecté)        : {
  nom: 'api-formation',
  port: 3000,
  environnement: 'development',
  maxStagiaires: 30
}
typeof app.port      : number
limite atteinte à 31 ? true
get('database.hote') : localhost
get('database')      : {
  hote: 'localhost',
  port: 3306,
  utilisateur: 'apc_dev',
  motDePasse: 'secret_dev',
  nom: 'formation_dev'
}
  • @Inject(appConfig.KEY) avec le type ConfigType<typeof appConfig> injecte l'objet complet et typé: l'éditeur propose this.app.port, et port est bien un nombre. C'est la forme recommandée.
  • config.get('database.hote'): accès par chemin pointé, pratique mais sans typage automatique.
  • registerAs est exécuté après le chargement du fichier .env: process.env y contient déjà ses valeurs.
La configuration dans main.ts et dans une fabrique

Deux endroits où l'on ne peut pas utiliser l'injection par constructeur : main.ts (on récupère le service avec app.get()) et les providers créés par useFactory (on liste ConfigService dans inject, leçon 7.4) :

📄 src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import databaseConfig from './config/database.config';

export const CONNEXION = Symbol('CONNEXION');

@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true, load: [databaseConfig] })],
  providers: [
    {
      provide: CONNEXION,
      inject: [ConfigService],
      useFactory: async (config: ConfigService) => {
        const db = config.getOrThrow<{ hote: string; port: number; nom: string; utilisateur: string }>('database');
        // au chapitre 11 : TypeOrmModule.forRootAsync({ inject: [ConfigService], useFactory: … })
        return `mysql://${db.utilisateur}@${db.hote}:${db.port}/${db.nom}`;
      },
    },
  ],
  exports: [CONNEXION],
})
export class AppModule {}

📄 src/main.ts

import 'reflect-metadata';
import { ConfigService } from '@nestjs/config';
import { NestFactory } from '@nestjs/core';
import { AppModule, CONNEXION } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { logger: false });
  const config = app.get(ConfigService);                       // ConfigService dans main.ts
  const port = Number(config.get('PORT', 3000));
  console.log('connexion :', app.get(CONNEXION));
  await app.listen(port);
  console.log(`API démarrée sur le port ${port}`);
  await app.close();
}
bootstrap();

Résultat réellement obtenu :

$ node dist/main.js
connexion : mysql://apc_dev@localhost:3306/formation_dev
API démarrée sur le port 3000

$ PORT=3999 DB_HOTE=mysql.interne node dist/main.js
connexion : mysql://apc_dev@mysql.interne:3306/formation_dev
API démarrée sur le port 3999

Ce schéma est exactement celui que vous utiliserez au chapitre 11 pour la connexion à MySQL : TypeOrmModule.forRootAsync({ inject: [ConfigService], useFactory: (config) => ({ host: config.get('database.hote'), … }) }). Changer de serveur de base de données ne demande alors plus aucune modification du code.

Ne lisez pas process.env directement dans vos services une fois @nestjs/config installé : la valeur ne serait pas validée, et le service deviendrait difficile à tester. Avec ConfigService ou un objet injecté par appConfig.KEY, un test fournit simplement une configuration avec useValue (leçon 7.4).

Activités

Activité 1 Remplacer les valeurs en dur

Dans api-formation-securisee, installez @nestjs/config, activez ConfigModule.forRoot({ isGlobal: true }), et utilisez ConfigService dans main.ts pour le port et la liste des origines CORS (CORS_ORIGINES=http://localhost:4200,http://localhost:5173).

Voir le corrigé
const app = await NestFactory.create(AppModule);
const config = app.get(ConfigService);
const origines = config.get<string>('CORS_ORIGINES', 'http://localhost:4200').split(',').map((o) => o.trim());
app.enableCors({ origin: origines, exposedHeaders: ['X-Correlation-Id', 'X-Duree-Ms'] });
await app.listen(Number(config.get('PORT', 3000)));

Remarquez le Number(…) autour du port : get ne convertit rien.

Activité 2 Un fichier securite.config.ts

Créez src/config/securite.config.ts avec registerAs('securite', …) qui lit CLES_API sous la forme cle1:admin,cle2:formateur et la transforme en objet { [cle]: role }. Injectez-le dans le CleApiGuard du TP 6 à la place du dictionnaire écrit en dur.

Voir le corrigé
export default registerAs('securite', () => {
  const brut = process.env.CLES_API ?? '';
  const cles: Record<string, string> = {};
  for (const paire of brut.split(',').filter(Boolean)) {
    const [cle, role] = paire.split(':').map((x) => x.trim());
    if (cle && role) cles[cle] = role;
  }
  return { cles };
});

// guard
constructor(
  private readonly reflector: Reflector,
  @Inject(securiteConfig.KEY) private readonly securite: ConfigType<typeof securiteConfig>,
) {}
// … const role = this.securite.cles[req.header('x-api-key') ?? ''];

Les clés ne sont plus dans le code ni dans le dépôt : chaque environnement a les siennes.

Activité 3 get ne convertit pas

Un étudiant écrit if (this.config.get<number>('MAX_STAGIAIRES') >= 30) avec MAX_STAGIAIRES=100. Le code fonctionne. Puis il écrit const total = this.config.get<number>('MAX_STAGIAIRES') + inscrits. Qu'obtient-il pour 5 inscrits ? Pourquoi le premier test fonctionnait-il ?

Voir le corrigé

"1005": la chaîne "100" est concaténée avec 5. Le premier test fonctionnait par chance : la comparaison >= entre une chaîne et un nombre convertit la chaîne en nombre. Le typage <number> a trompé le compilateur. Solution : configuration typée (registerAs) ou validation avec conversion.

Activité 4 Tester avec une configuration

Écrivez un test (@nestjs/testing) de StagiairesService qui fournit appConfig.KEY avec useValue: { maxStagiaires: 2, … }, sans fichier .env.

Voir le corrigé
const module = await Test.createTestingModule({
  providers: [
    StagiairesService,
    { provide: appConfig.KEY, useValue: { nom: 'test', port: 0, environnement: 'test', maxStagiaires: 2 } },
    { provide: ConfigService, useValue: { get: () => undefined } },
  ],
}).compile();

const service = module.get(StagiairesService);

Le service reçoit une configuration maîtrisée : on peut tester la limite de 2 stagiaires sans toucher à l'environnement de la machine.

À retenir

  • npm install @nestjs/config, puis ConfigModule.forRoot({ isGlobal: true }) dans AppModule.
  • ConfigService.get(clé, défaut) et getOrThrow(clé) ; get NE convertit PAS.
  • registerAs('domaine', () => ({ … })) + load : configuration typée et convertie une seule fois.
  • @Inject(appConfig.KEY) avec ConfigType : objet typé injecté.
  • main.ts : app.get(ConfigService) ; fabriques : inject: [ConfigService] (TypeORM au chapitre 11).

Cet article vous a-t-il aidé ?