Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fastify/env-schema
Validate your env variable using Ajv and dotenv
https://github.com/fastify/env-schema
environment environment-variables fastify-library json-schema validation
Last synced: 27 days ago
JSON representation
Validate your env variable using Ajv and dotenv
- Host: GitHub
- URL: https://github.com/fastify/env-schema
- Owner: fastify
- License: mit
- Created: 2019-02-15T11:35:10.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-08-12T09:44:09.000Z (3 months ago)
- Last Synced: 2024-09-28T11:21:40.929Z (about 1 month ago)
- Topics: environment, environment-variables, fastify-library, json-schema, validation
- Language: JavaScript
- Homepage:
- Size: 146 KB
- Stars: 215
- Watchers: 17
- Forks: 25
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# env-schema
[](https://github.com/fastify/env-schema/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/env-schema)
[](https://standardjs.com/)
Utility to check environment variables using [JSON schema](https://json-schema.org/), [Ajv](http://npm.im/ajv), and
[dotenv](http://npm.im/dotenv).
See [supporting resources](#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 }
```
see [DotenvConfigOptions](https://github.com/motdotla/dotenv#options)
### Custom ajv instance
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` function parameter.
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
}
}
})
```
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](http://npm.im/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, // 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:
```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'] }
```
### TypeScript
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](https://github.com/lirantal/fastify-dotenv-envschema-example)
## Acknowledgements
Kindly sponsored by [Mia Platform](https://www.mia-platform.eu/) and
[NearForm](https://nearform.com).
## License
MIT