env-schema
Utility to check environment variables using JSON schema, Ajv, and dotenv.
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 }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 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:
- Data sourced from
.envfile (whendotenvconfiguration option is set) - Data sourced from environment variables in
process.env - Data provided via the
dataconfiguration 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, // use dotenv-expand, 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
Acknowledgements
Kindly sponsored by Mia Platform and NearForm.
License
MIT