0Pricing
NestJS Enterprise Backend APIs · レッスン

JoiとforRootによるスキーマ検証済みEnv

ConfigModule.forRootでJoiスキーマを使って環境変数を検証し、起動時にすぐ失敗を検出します

「JoiとforRootによるスキーマ検証済みEnv」はCoddyKit上の無料NestJS Enterprise Backend APIsレッスンです。 これはレッスン1/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはNestJS Enterprise Backend APIs学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 NestJS Enterprise Backend APIsコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

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.

よくある質問

「JoiとforRootによるスキーマ検証済みEnv」レッスンは無料ですか？

はい。「JoiとforRootによるスキーマ検証済みEnv」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、NestJS Enterprise Backend APIsコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 NestJS Enterprise Backend APIsコースには全4レッスンが含まれています。

「JoiとforRootによるスキーマ検証済みEnv」で何を学びますか？

ConfigModule.forRootでJoiスキーマを使って環境変数を検証し、起動時にすぐ失敗を検出します ブラウザで直接実行するハンズオンコードでNestJS Enterprise Backend APIsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

NestJS Enterprise Backend APIsを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのNestJS Enterprise Backend APIsは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。

「JoiとforRootによるスキーマ検証済みEnv」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このNestJS Enterprise Backend APIsレッスンでコードを書いて実行できますか？

はい。すべてのNestJS Enterprise Backend APIsレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. JoiとforRootによるスキーマ検証済みEnv
  2. registerAsによる名前空間付きConfig
  3. HashiCorp VaultとAWS SSMからSecretsを読み込む
  4. 環境別Configと安全なデフォルト値
← NestJS Enterprise Backend APIsに戻る