nested-env-schema

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

Install

pnpm add nested-env-schema

Usage

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

Custom ajv instance

Optionally, the user can supply their own ajv instance:

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.

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.

Order of configuration loading

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

Custom keywords

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:

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:

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'] }

TypeScript

You can specify the type of your config:

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

interface Env {
  PORT: number;
}

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

const config = envSchema({
  schema,
});

You can also use a JSON Schema library like typebox:

import { envSchema } from 'nested-env-schema';
import { Static, Type } from '@sinclair/typebox';

const schema = Type.Object({
  PORT: Type.Number({ default: 3000 }),
});

type Schema = Static<typeof schema>;

const config = envSchema<Schema>({
  schema,
});

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

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

Acknowledgements

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

License

MIT