nested-env-schema


Validate & extract your env variables using nested JSON schema, Ajv and
dotenvx.

Install

``
pnpm add nested-env-schema
`

Usage

`js
const envSchema = require('nested-env-schema');

const schema = {
type: 'object',
required: ['PORT', 'SENTRY'],
properties: {
// Reads the PORT env var
PORT: {
type: 'number',
default: 3000,
},
SENTRY: {
type: 'object',
required: ['ENABLED', 'DSN'],
properties: {
// Reads the SENTRY_ENABLED env var
ENABLED: {
type: 'boolean',
default: false,
},
// Reads the SENTRY_DSN env var
DSN: {
type: 'string'
default: 'something',
},
},
},
},
};

const config = envSchema({
schema: schema,
data: data, // optional, default: process.env
dotenv: true, // load .env file if it is there, default: false
// or you can pass DotenvConfigOptions
// dotenv: {
// path: '/custom/path/to/.env'
// }
});

console.log(config);
// output: { PORT: 3000, SENTRY: { ENABLED: false, DSN: 'something' } }
`

see DotenvConfigOptions

$3

Optionally, the user can supply their own ajv instance:

`js
const envSchema = require('nested-env-schema');
const Ajv = require('ajv');

const schema = {
type: 'object',
required: ['PORT'],
properties: {
PORT: {
type: 'number',
default: 3000,
},
},
};

const config = envSchema({
schema: schema,
data: data,
dotenv: true,
ajv: new Ajv({
allErrors: true,
removeAdditional: true,
useDefaults: true,
coerceTypes: true,
allowUnionTypes: true,
}),
});

console.log(config);
// output: { PORT: 3000 }
`

It is possible to enhance the default ajv instance providing the customOptions function parameter.
This example shows how to use the format keyword in your schemas.

`js
const config = envSchema({
schema: schema,
data: data,
dotenv: true,
ajv: {
customOptions(ajvInstance) {
require('ajv-formats')(ajvInstance);
return ajvInstance;
},
},
});
`

Note that it is mandatory returning the ajv instance.

$3

The order of precedence for configuration data is as follows, from least
significant to most:

1. Data sourced from .env file (when dotenv configuration option is set)
2. Data sourced from environment variables in process.env
3. Data provided via the data configuration option

$3

This library supports the following Ajv custom keywords:

#### separator

Type: string

Applies to type: string

When present, the provided schema value will be split on this value.

Example:

`js
const envSchema = require('nested-env-schema');

const schema = {
type: 'object',
required: ['ALLOWED_HOSTS'],
properties: {
ALLOWED_HOSTS: {
type: 'string',
separator: ',',
},
},
};

const data = {
ALLOWED_HOSTS: '127.0.0.1,0.0.0.0',
};

const config = envSchema({
schema: schema,
data: data, // optional, default: process.env
dotenv: true, // load .env if it is there, default: false
});

// config.ALLOWED_HOSTS => ['127.0.0.1', '0.0.0.0']
`

The ajv keyword definition objects can be accessed through the property keywords on the envSchema function:

`js
const envSchema = require('nested-env-schema');
const Ajv = require('ajv');

const schema = {
type: 'object',
properties: {
names: {
type: 'string',
separator: ',',
},
},
};

const config = envSchema({
schema: schema,
data: data,
dotenv: true,
ajv: new Ajv({
allErrors: true,
removeAdditional: true,
useDefaults: true,
coerceTypes: true,
allowUnionTypes: true,
keywords: [envSchema.keywords.separator],
}),
});

console.log(config);
// output: { names: ['foo', 'bar'] }
`

$3

You can specify the type of your config:

`ts
import { envSchema, JSONSchemaType } from 'nested-env-schema';

interface Env {
PORT: number;
}

const schema: JSONSchemaType = {
type: 'object',
required: ['PORT'],
properties: {
PORT: {
type: 'number',
default: 3000,
},
},
};

const config = envSchema({
schema,
});
`

You can also use a JSON Schema library like zod:

`ts
import { envSchema } from 'nested-env-schema';
import { z } from 'zod/v4';

const schema = z.object({
PORT: z.number().default(3000),
});

type Schema = z.infer;

const config = envSchema({
schema: z.toJSONSchema(schema),
});
`

If no type is specified the config will have the EnvSchemaData type.

`ts
export type EnvSchemaData = {
[key: string]: unknown;
};
``

Acknowledgements

Forked from https://github.com/fastify/env-schema

License

MIT