env-schema

Validate your env variable using Ajv and dotenv

ConfigurationValidation
fastify/env-schemaenv-schema

README

env-schema


Utility to check environment variables using JSON schema, Ajv, and
dotenv.

See supporting resources section for helpful guides on getting started.

Install


  1. ```
  2. npm i env-schema
  3. ```

Usage


  1. ```js
  2. const envSchema = require('env-schema')

  4. const schema = {
  5.   type: 'object',
  6.   required: [ 'PORT' ],
  7.   properties: {
  8.     PORT: {
  9.       type: 'number',
  10.       default: 3000
  11.     }
  12.   }
  13. }

  15. const config = envSchema({
  16.   schema: schema,
  17.   data: data, // optional, default: process.env
  18.   dotenv: true // load .env if it is there, default: false
  19.   // or you can pass DotenvConfigOptions
  20.   // dotenv: {
  21.   //   path: '/custom/path/to/.env'
  22.   // }
  23. })

  25. console.log(config)
  26. // output: { PORT: 3000 }
  27. ```

see DotenvConfigOptions

Custom ajv instance


Optionally, the user can supply their own ajv instance:

  1. ```js
  2. const envSchema = require('env-schema')
  3. const Ajv = require('ajv')

  5. const schema = {
  6.   type: 'object',
  7.   required: [ 'PORT' ],
  8.   properties: {
  9.     PORT: {
  10.       type: 'number',
  11.       default: 3000
  12.     }
  13.   }
  14. }

  16. const config = envSchema({
  17.   schema: schema,
  18.   data: data,
  19.   dotenv: true,
  20.   ajv: new Ajv({
  21.     allErrors: true,
  22.     removeAdditional: true,
  23.     useDefaults: true,
  24.     coerceTypes: true,
  25.     allowUnionTypes: true
  26.   })
  27. })

  29. console.log(config)
  30. // output: { PORT: 3000 }
  31. ```

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.

  1. ```js
  2. const config = envSchema({
  3.   schema: schema,
  4.   data: data,
  5.   dotenv: true,
  6.   ajv: {
  7.     customOptions (ajvInstance) {
  8.       require('ajv-formats')(ajvInstance)
  9.       return ajvInstance
  10.     }
  11.   }
  12. })
  13. ```

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

Fluent-Schema API


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

  1. ```js
  2. const envSchema = require('env-schema')
  3. const S = require('fluent-json-schema')

  5. const config = envSchema({
  6.   schema: S.object().prop('PORT', S.number().default(3000).required()),
  7.   data: data, // optional, default: process.env
  8.   dotenv: true, // load .env if it is there, default: false
  9.   expandEnv: true, // use dotenv-expand, default: false
  10. })

  12. console.log(config)
  13. // output: { PORT: 3000 }
  14. ```

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:
  1. ```js
  2. const envSchema = require('env-schema')

  4. const schema = {
  5.   type: 'object',
  6.   required: [ 'ALLOWED_HOSTS' ],
  7.   properties: {
  8.     ALLOWED_HOSTS: {
  9.       type: 'string',
  10.       separator: ','
  11.     }
  12.   }
  13. }

  15. const data = {
  16.   ALLOWED_HOSTS: '127.0.0.1,0.0.0.0'
  17. }

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

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

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

  1. ```js
  2. const envSchema = require('env-schema')
  3. const Ajv = require('ajv')

  5. const schema = {
  6.   type: 'object',
  7.   properties: {
  8.     names: {
  9.       type: 'string',
  10.       separator: ','
  11.     }
  12.   }
  13. }

  15. const config = envSchema({
  16.   schema: schema,
  17.   data: data,
  18.   dotenv: true,
  19.   ajv: new Ajv({
  20.     allErrors: true,
  21.     removeAdditional: true,
  22.     useDefaults: true,
  23.     coerceTypes: true,
  24.     allowUnionTypes: true,
  25.     keywords: [envSchema.keywords.separator]
  26.   })
  27. })

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

TypeScript


You can specify the type of your config:

  1. ```ts
  2. import { envSchema, JSONSchemaType } from 'env-schema'

  4. interface Env {
  5.   PORT: number;
  6. }

  8. const schema: JSONSchemaType<Env> = {
  9.   type: 'object',
  10.   required: [ 'PORT' ],
  11.   properties: {
  12.     PORT: {
  13.       type: 'number',
  14.       default: 3000
  15.     }
  16.   }
  17. }

  19. const config = envSchema({
  20.   schema
  21. })
  22. ```

You can also use a JSON Schema library like typebox:

  1. ```ts
  2. import { envSchema } from 'env-schema'
  3. import { Static, Type } from '@sinclair/typebox'

  5. const schema = Type.Object({
  6.   PORT: Type.Number({ default: 3000 })
  7. })

  9. type Schema = Static<typeof schema>

  11. const config = envSchema<Schema>({
  12.   schema
  13. })
  14. ```

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

  1. ```ts
  2. export type EnvSchemaData = {
  3.   [key: string]: unknown;
  4. }
  5. ```

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

Acknowledgements


Kindly sponsored by Mia Platform and
NearForm.

License


MIT