env-schema

env-schema

Utility to check environment variables using JSON schema, Ajv, with .env file support using Node.js built-in parseEnv from node:util.

See supporting resources section for helpful guides on getting started.

Install

npm i env-schema

Usage

const envSchema = require('env-schema')

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

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

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

Supported .env file options:

• path (string): Path to the .env file (default: '.env')
• encoding (string): File encoding (default: 'utf8')

Custom ajv instance

Optionally, the user can supply their own ajv instance:

const envSchema = require('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 as a function or object parameter.

When customOptions is an object, the provided ajv options override the default ones:

const config = envSchema({
  schema: schema,
  data: data,
  dotenv: true,
  ajv: {
    customOptions: {
      coerceTypes: true
    }
  }
})

When customOptions is a function, it must return the updated ajv instance. 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
    }
  }
})

Order of configuration loading

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

• Data sourced from .env file (when dotenv configuration option is set) - parsed using Node.js built-in parseEnv
• Data sourced from environment variables in process.env
• Data provided via the data configuration option

Fluent-Schema API

It is also possible to use fluent-json-schema:

const envSchema = require('env-schema')
const S = require('fluent-json-schema')

const config = envSchema({
  schema: S.object().prop('PORT', S.number().default(3000).required()),
  data: data, // optional, default: process.env
  dotenv: true, // load .env if it is there, default: false
  expandEnv: true, // expand environment variables like $VAR or ${VAR}, default: false
})

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

NB Support for additional properties in the schema is disabled for this plugin, with the additionalProperties flag set to false internally.

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('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('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 '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 '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;
}

Supporting resources

The following section lists helpful reference applications, articles, guides, and other resources that demonstrate the use of env-schema in different use cases and scenarios:

• A reference application using Fastify with env-schema and dotenv

Acknowledgments

Kindly sponsored by Mia Platform and NearForm.

License

Licensed under MIT.

Similar packages

Other packages similar to env-schema

joi

Joi is a powerful schema description language and data validator for JavaScript. It can be used to validate environment variables, but it is more general-purpose and can validate any JavaScript object. Compared to env-schema, Joi offers more flexibility and a richer set of validation features, but it requires more setup for environment variable validation.

dotenv

Dotenv is a zero-dependency module that loads environment variables from a .env file into process.env. While it does not provide schema validation, it is often used in conjunction with validation libraries like Joi or env-schema to manage environment variables in Node.js applications.

convict

Convict is a configuration management tool for Node.js that allows you to define a schema for your configuration, including environment variables. It provides validation, default values, and type coercion similar to env-schema, but it also includes features for managing configuration files and command-line arguments.