Variáveis de Ambiente Validadas pelo Esquema com Joi e forRoot

Why Validate Env at Boot?

The Problem Without Validation

// 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

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

A First Joi Schema

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

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

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

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

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

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

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

// 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

Recap