0Pricing
NestJS Enterprise Backend APIs · Leçon

Variables d’environnement validées par schéma avec Joi et forRoot

Échouez rapidement au démarrage en validant les variables d’environnement avec un schéma Joi dans ConfigModule.forRoot.

Variables d’environnement validées par schéma avec Joi et forRoot est une leçon NestJS Enterprise Backend APIs gratuite sur CoddyKit. Ceci est la leçon 1 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage NestJS Enterprise Backend APIs, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours NestJS Enterprise Backend APIs comprend 4 leçons au total.

Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.

Why Validate Env at Boot?

In enterprise NestJS services, configuration lives in environment variables. A missing DATABASE_URL or a typo like PORT=tree should never reach production traffic.

  • Fail fast: crash at startup, not on the first request three hours later.
  • Single source of truth: one schema documents every variable your app needs.
  • Type safety: coerce strings into numbers and booleans up front.

This lesson wires a Joi schema into ConfigModule.forRoot so the process refuses to boot when the environment is invalid.

The Problem Without Validation

Without validation, NestJS happily starts with bad config. The failure surfaces later, deep inside a service, with a confusing error.

Below, PORT arrives as a string and the math silently breaks. A real app would also dereference undefined secrets at runtime.

// A common silent bug: env vars are always strings
const PORT = process.env.PORT; // "3000" or undefined

// Expecting a number, but string concatenation happens instead
const nextPort = PORT + 1;
console.log('PORT:', PORT);
console.log('nextPort (wrong):', nextPort); // "30001", not 3001

// Missing secret is undefined, not an error
const secret = process.env.JWT_SECRET;
console.log('JWT_SECRET present?', secret !== undefined);

Installing the Pieces

You need two packages: the Nest config module and Joi itself.

  • @nestjs/config wraps dotenv and exposes ConfigService.
  • joi is the schema/validation library that forRoot calls internally.

Joi ships its own TypeScript types, so no separate @types package is required.

# Install the config module and Joi
npm install @nestjs/config joi

A First Joi Schema

A Joi schema is an object describing each variable's type, allowed values, and defaults. Validation runs against process.env.

This snippet is plain Node + Joi (no Nest), so you can see exactly what forRoot does under the hood.

const Joi = require('joi');

const schema = Joi.object({
  NODE_ENV: Joi.string()
    .valid('development', 'production', 'test')
    .default('development'),
  PORT: Joi.number().port().default(3000),
});

const { error, value } = schema.validate(
  { PORT: '8080' },
  { abortEarly: false, allowUnknown: true },
);

console.log('error:', error ? error.message : 'none');
console.log('PORT type:', typeof value.PORT, value.PORT); // number 8080
console.log('NODE_ENV default:', value.NODE_ENV);

Wiring the Schema into forRoot

Pass the schema as validationSchema to ConfigModule.forRoot. Use isGlobal: true so ConfigService is injectable everywhere without re-importing.

If the environment fails the schema, Nest throws during module initialization and the process exits non-zero.

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import * as Joi from 'joi';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validationSchema: Joi.object({
        NODE_ENV: Joi.string()
          .valid('development', 'production', 'test')
          .default('development'),
        PORT: Joi.number().port().default(3000),
        DATABASE_URL: Joi.string().uri().required(),
        JWT_SECRET: Joi.string().min(32).required(),
      }),
    }),
  ],
})
export class AppModule {}

Required vs Default

The two most important Joi modifiers shape your fail-fast policy:

  • .required() — boot must fail if the variable is absent. Use for secrets and connection strings.
  • .default(value) — supply a safe fallback so the variable is optional.

Never give a secret like JWT_SECRET a default; that hides a misconfiguration and ships a known key.

import * as Joi from 'joi';

export const validationSchema = Joi.object({
  // Optional with a sensible fallback
  LOG_LEVEL: Joi.string()
    .valid('debug', 'info', 'warn', 'error')
    .default('info'),

  // Mandatory: no default, must be provided
  DATABASE_URL: Joi.string().uri().required(),
  JWT_SECRET: Joi.string().min(32).required(),
});

Type Coercion and Booleans

Every env var is a string. Joi coerces them so ConfigService.get returns real types.

  • Joi.number() turns "5432" into 5432.
  • Joi.boolean() understands "true"/"false" as real booleans.

This coercion is the value Joi adds beyond a plain presence check.

const Joi = require('joi');

const schema = Joi.object({
  DB_PORT: Joi.number().default(5432),
  CACHE_ENABLED: Joi.boolean().default(false),
});

const { value } = schema.validate(
  { DB_PORT: '6543', CACHE_ENABLED: 'true' },
  { allowUnknown: true },
);

console.log(typeof value.DB_PORT, value.DB_PORT);       // number 6543
console.log(typeof value.CACHE_ENABLED, value.CACHE_ENABLED); // boolean true

validationOptions: Report Every Error

By default Joi stops at the first error (abortEarly: true). In CI and local setup you want the full list, so pass validationOptions.

  • abortEarly: false — collect and print all missing/invalid vars at once.
  • allowUnknown: true — tolerate extra OS vars like PATH (the default).
import { ConfigModule } from '@nestjs/config';
import * as Joi from 'joi';

ConfigModule.forRoot({
  isGlobal: true,
  validationSchema: Joi.object({
    DATABASE_URL: Joi.string().uri().required(),
    JWT_SECRET: Joi.string().min(32).required(),
    REDIS_URL: Joi.string().uri().required(),
  }),
  validationOptions: {
    abortEarly: false, // show ALL problems, not just the first
    allowUnknown: true,
  },
});

Conditional Rules with Joi.when

Enterprise configs differ per environment. Joi expresses this with .when(): tighten rules only in production.

Here, TLS must be enabled and a sentry DSN must be present when NODE_ENV is production, but stay optional otherwise.

import * as Joi from 'joi';

export const validationSchema = Joi.object({
  NODE_ENV: Joi.string()
    .valid('development', 'production', 'test')
    .default('development'),

  DB_SSL: Joi.boolean().when('NODE_ENV', {
    is: 'production',
    then: Joi.valid(true).required(),
    otherwise: Joi.boolean().default(false),
  }),

  SENTRY_DSN: Joi.string().uri().when('NODE_ENV', {
    is: 'production',
    then: Joi.required(),
    otherwise: Joi.optional(),
  }),
});

Reading Validated Config in a Service

Once validation passes, inject ConfigService and read typed values. Use the generic form get<number> for the right return type.

Because the schema guarantees presence, you can safely assert non-null for required keys.

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

@Injectable()
export class DatabaseConfig {
  constructor(private readonly config: ConfigService) {}

  get url(): string {
    // Required in the schema, so it is guaranteed present
    return this.config.get<string>('DATABASE_URL')!;
  }

  get port(): number {
    // Already coerced to a number by Joi
    return this.config.get<number>('DB_PORT', 5432);
  }
}

What a Boot Failure Looks Like

When validation fails, Nest throws before listening on the port. The message lists each offending variable, which is gold for debugging deploys.

A typical crash with abortEarly: false reports multiple problems together.

// Simulated message thrown by @nestjs/config on bad env
// Error: Config validation error:
//   "DATABASE_URL" is required.
//   "JWT_SECRET" length must be at least 32 characters long.
//   "PORT" must be a valid port.
//
// Process exits with a non-zero code; no requests are served.

console.log('Boot aborted: fix the env vars listed above.');

Quick Check

Test your understanding of fail-fast env validation.

Recap

You made configuration fail fast with Joi:

  • Pass a Joi.object schema as validationSchema to ConfigModule.forRoot, with isGlobal: true.
  • Mark secrets and connection strings .required(); give safe values .default(); never default a secret.
  • Joi coerces strings into numbers and booleans, so ConfigService.get returns real types.
  • Set validationOptions.abortEarly: false to surface every problem at once.
  • Use .when() to enforce stricter rules in production.

The payoff: a broken environment crashes at startup with a clear list, never silently mid-request.

Questions Fréquemment Posées

La leçon « Variables d’environnement validées par schéma avec Joi et forRoot » est-elle gratuite ?

Oui — le texte complet de « Variables d’environnement validées par schéma avec Joi et forRoot » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours NestJS Enterprise Backend APIs, passe à CoddyKit PRO. Le cours NestJS Enterprise Backend APIs comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Variables d’environnement validées par schéma avec Joi et forRoot » ?

Échouez rapidement au démarrage en validant les variables d’environnement avec un schéma Joi dans ConfigModule.forRoot. Tu pratiques NestJS Enterprise Backend APIs avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer NestJS Enterprise Backend APIs ?

Aucune expérience préalable n'est requise. NestJS Enterprise Backend APIs sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 1 sur 4.

Combien de temps prend la leçon « Variables d’environnement validées par schéma avec Joi et forRoot » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon NestJS Enterprise Backend APIs ?

Oui. Chaque leçon NestJS Enterprise Backend APIs inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Variables d’environnement validées par schéma avec Joi et forRoot
  2. Configuration avec espaces de noms et registerAs
  3. Charger des secrets depuis HashiCorp Vault et AWS SSM
  4. Configuration par environnement et valeurs par défaut sûres
← Retour à NestJS Enterprise Backend APIs