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

`js
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')

$3

Optionally, the user can supply their own ajv instance:

`js
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:

`js
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.

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

$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) - parsed using Node.js built-in parseEnv
2. Data sourced from environment variables in process.env
3. Data provided via the data configuration option

$3

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

`js
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.

$3

#### separator
Type: string

Applies to type: string

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

Example:
`js
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:

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

$3

You can specify the type of your config:

`ts
import { envSchema, JSONSchemaType } from '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 typebox:

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

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

type Schema = Static

const config = envSchema({
schema
})
`

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

`ts
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.