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
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
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 ,
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
}
}
}) copy
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
}
}
}) copy
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, ${VAR}, ${VAR:-default} or ${VAR-default} (\$ for a literal $), default: false
})
console. log (config)
// output: { PORT: 3000 } copy
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
})
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 ,
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
}) copy
You can also use a JSON Schema library like typebox:
import { envSchema } from 'env-schema'
import { Static, Type } from 'typebox'
const schema = Type. Object ({
PORT: Type. Number ({ default: 3000 })
})
type Schema = Static < typeof schema>
const config = envSchema < Schema >({
schema
}) copy
If no type is specified the config will have the EnvSchemaData type.
export type EnvSchemaData = {
[key : string ] : unknown ;
} copy
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:
Acknowledgments
Kindly sponsored by Mia Platform and
NearForm .
License
Licensed under MIT .