nestjs-zod-config - NestJS module to load, type and validate configuration using Zod. Inside and outside the NestJS context.
We are also providing some handy utility functions. ✨
yarn add nestjs-zod-configPeer dependencies:
yarn add @nestjs/common zod
The first thing that we need to do is to create a config class that extends ZodConfig and pass it our Zod schema.
// app.config.ts
import { ZodConfig } from 'nestjs-zod-config';
import { z } from 'zod';
const appConfigSchema = z.object({
HOSTNAME: z.string().min(1).default('0.0.0.0'),
PORT: z.coerce.number().default(3000),
});
export class AppConfig extends ZodConfig(appConfigSchema) {}
// You can also pass a custom path to the .env file(s)
export class AppConfig extends ZodConfig(appConfigSchema, {
envFilePath: '.env.custom'
})By default, this assumes that you have a
.envfile in the root of your project or that you have set the environment variables inprocess.envin some other way. You can customize the path to the .env file using theenvFilePathoption.
✨ All done. Let's see how we can use it.
We will have to register the config class in a module:
// app.module.ts
import { Module } from '@nestjs/common';
import { ZodConfigModule } from 'nestjs-zod-config';
import { AppConfig } from './app.config';
@Module({
imports: [
ZodConfigModule.forRoot({
config: AppConfig,
isGlobal: true, // optional, defaults to `false`
}),
],
})
export class AppModule {}It is recommended to register the config class in the root module of your application.
Now we can inject AppConfig in your services like this:
// app.service.ts
import { Injectable } from '@nestjs/common';
import { AppConfig } from './app.config';
@Injectable()
export class AppService {
constructor(private readonly appConfig: AppConfig) {}
getPort(): number {
return this.appConfig.get('PORT');
}
}or in our main.ts, like this:
// main.ts
import { NestFactory } from '@nestjs/core';
import { AppConfig } from './app.config';
import { AppModule } from './app.module';
const main = async () => {
const app = await NestFactory.create(AppModule);
const appConfig = app.get(AppConfig);
const hostname = appConfig.get('HOSTNAME');
const port = appConfig.get('PORT');
await app.listen(port, hostname);
};
void main();There are cases where we need to access the config outside the NestJS context. For example, we might want to use the config in a seeder script:
// seed.ts
import { loadZodConfig } from 'nestjs-zod-config';
const seedDb = async () => {
const appConfig = loadZodConfig(AppConfig);
const databaseurl = appConfig.get('DATABASE_URL');
// use the `databaseurl` to connect to the database and seed it
};In this case we cannot inject the
AppConfigand we don't have access to theappinstance. The file is executed outside the NestJS context.
This is a utility function that can be used to coerce a string value to a boolean in a strict manner.
Normally you will do: z.coerce.boolean() but this will also coerce the string 'false' to true.
So instead we use this function to only allow 'false' or false to be coerced to false, 'true' or true to true and everything else will throw an error.
// In your schema
const configSchema = z.object({
DEBUG_MODE: safeBooleanCoerce,
});
// When parsed:
// "true" or true -> true
// "false" or false -> false
// Any other value -> Error: "Invalid boolean value"This is a utility function that can be used to parse a comma-delimited string into an array of strings.
It's particularly useful when dealing with environment variables that contain multiple values separated by commas. For example, you might have an environment variable like ALLOWED_ORIGINS=http://localhost:3000,https://example.com that you want to parse into an array.
// In your schema
const configSchema = z.object({
ALLOWED_ORIGINS: commaDelimitedArray,
});
// When parsed, this will transform "http://localhost:3000,https://example.com" into:
// ["http://localhost:3000", "https://example.com"]The function trims whitespace from each item and ensures the array contains at least one element. If the input is not a string, it will throw a validation error.
This is a utility function that can be used to transform a JSON string into an object. It's particularly useful when dealing with environment variables that contain JSON data.
// In your schema
const configSchema = z.object({
SERVICE_ACCOUNT: jsonStringCoerce.pipe(
z.object({
type: z.literal('service_account'),
project_id: z.string().min(1),
private_key_id: z.string().min(1),
private_key: z.string().min(1),
client_email: z.string().min(1),
client_id: z.string().min(1),
auth_uri: z.string().url(),
token_uri: z.string().url(),
auth_provider_x509_cert_url: z.string().url(),
client_x509_cert_url: z.string().url(),
}).required(),
),
});
// When parsed, this will transform a JSON string like:
// '{"type":"service_account","project_id":"my-project",...}'
// into a properly validated object with the specified structureThe function first attempts to parse the input string as JSON. If parsing fails, it will throw a validation error with the message "Invalid JSON string - cannot be parsed". After successful parsing, you can pipe the result to additional Zod schemas for further validation and transformation.
This is a utility function that can be used to coerce a string to a date in a strict manner.
When using z.coerce.date(), you might get unexpected results. For example, z.coerce.date().parse(null) returns 1970-01-01T00:00:00.000Z, which may not be the desired behavior in many cases.
This utility is particularly useful in DTOs where null or undefined may be passed, but their resolution to a date is not desired. It ensures that only valid string representations of dates are coerced to Date objects.
// In your schema
const configSchema = z.object({
EXPIRATION_DATE: strictCoerceStringDate,
});
// When parsed:
// "2023-01-01" -> Date object (2023-01-01T00:00:00.000Z)
// null or undefined -> Error: Expected string, received null/undefined