Validate your env variable using Ajv and dotenv
MIT License
Utility to check environment variables using JSON schema, Ajv, and dotenv.
See supporting resources section for helpful guides on getting started.
npm i env-schema
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 }
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.
The order of precedence for configuration data is as follows, from least significant to most:
.env
file (when dotenv
configuration option is set)process.env
data
configuration optionIt 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.
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'] }
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;
}
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:
Kindly sponsored by Mia Platform and NearForm.
MIT