0Pricing
NestJS Enterprise Backend APIs · Lesson

Schema-Validated Env with Joi and forRoot

Fail fast at boot by validating environment variables with a Joi schema in ConfigModule.forRoot.

Schema-Validated Env with Joi and forRoot is a free NestJS Enterprise Backend APIs lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the NestJS Enterprise Backend APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

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.

Frequently asked questions

Is the “Schema-Validated Env with Joi and forRoot” lesson free?

Yes — the full text of “Schema-Validated Env with Joi and forRoot” is free to read here on the web, and the NestJS Enterprise Backend APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the NestJS Enterprise Backend APIs course, upgrade to CoddyKit PRO.

What will I learn in “Schema-Validated Env with Joi and forRoot”?

Fail fast at boot by validating environment variables with a Joi schema in ConfigModule.forRoot. You practise NestJS Enterprise Backend APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start NestJS Enterprise Backend APIs?

No prior experience is required. NestJS Enterprise Backend APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Schema-Validated Env with Joi and forRoot” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this NestJS Enterprise Backend APIs lesson?

Yes. Every NestJS Enterprise Backend APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Schema-Validated Env with Joi and forRoot
  2. Namespaced Config with registerAs
  3. Loading Secrets from HashiCorp Vault and AWS SSM
  4. Per-Environment Config and Safe Defaults
← Back to NestJS Enterprise Backend APIs