NestJS Enterprise Backend APIs · Lezione

Variabili d’ambiente validate dallo schema con Joi e forRoot

Interrompa subito l’avvio validando le variabili d’ambiente con uno schema Joi in ConfigModule.forRoot.

Lezione 1 di 413 passaggi

Variabili d’ambiente validate dallo schema con Joi e forRoot è una lezione NestJS Enterprise Backend APIs gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento NestJS Enterprise Backend APIs, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso NestJS Enterprise Backend APIs include 4 lezioni in totale.

Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.

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.

Rispondi nella lezione interattiva

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.

Gratis per iniziare

Impara TypeScript con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 20
Lezioni: 76

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Variabili d’ambiente validate dallo schema con Joi e forRoot» è gratuita?

Sì — il testo completo di «Variabili d’ambiente validate dallo schema con Joi e forRoot» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso NestJS Enterprise Backend APIs, passa a CoddyKit PRO. Il corso NestJS Enterprise Backend APIs include 4 lezioni in totale.

Cosa imparerò in «Variabili d’ambiente validate dallo schema con Joi e forRoot»?

Interrompa subito l’avvio validando le variabili d’ambiente con uno schema Joi in ConfigModule.forRoot. Eserciti NestJS Enterprise Backend APIs con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare NestJS Enterprise Backend APIs?

Non è richiesta alcuna esperienza precedente. NestJS Enterprise Backend APIs su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Variabili d’ambiente validate dallo schema con Joi e forRoot»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione NestJS Enterprise Backend APIs?

Sì. Ogni lezione NestJS Enterprise Backend APIs include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Variabili d’ambiente validate dallo schema con Joi e forRoot
Configurazione con namespace tramite registerAs
Caricare i segreti da HashiCorp Vault e AWS SSM
Configurazione per ambiente e valori predefiniti sicuri

← Torna a NestJS Enterprise Backend APIs