https://github.com/pksunkara/nested-env-schema
Validate & extract your env variables using nested JSON schema, Ajv and dotenvx.
https://github.com/pksunkara/nested-env-schema
dotenvx
Last synced: 2 months ago
JSON representation
Validate & extract your env variables using nested JSON schema, Ajv and dotenvx.
- Host: GitHub
- URL: https://github.com/pksunkara/nested-env-schema
- Owner: pksunkara
- License: mit
- Created: 2023-07-19T17:34:03.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2025-06-16T20:22:18.000Z (12 months ago)
- Last Synced: 2025-06-16T20:28:01.401Z (12 months ago)
- Topics: dotenvx
- Language: JavaScript
- Homepage:
- Size: 167 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nested-env-schema
[](https://github.com/pksunkara/nested-env-schema/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/nested-env-schema)
Validate & extract your env variables using nested [JSON schema](https://json-schema.org/), [Ajv](http://npm.im/ajv) and
[dotenvx](https://dotenvx.com/).
## Install
```
pnpm add nested-env-schema
```
## Usage
```js
const envSchema = require('nested-env-schema');
const schema = {
type: 'object',
required: ['PORT', 'SENTRY'],
properties: {
// Reads the `PORT` env var
PORT: {
type: 'number',
default: 3000,
},
SENTRY: {
type: 'object',
required: ['ENABLED', 'DSN'],
properties: {
// Reads the `SENTRY_ENABLED` env var
ENABLED: {
type: 'boolean',
default: false,
},
// Reads the `SENTRY_DSN` env var
DSN: {
type: 'string'
default: 'something',
},
},
},
},
};
const config = envSchema({
schema: schema,
data: data, // optional, default: process.env
dotenv: true, // load .env file if it is there, default: false
// or you can pass DotenvConfigOptions
// dotenv: {
// path: '/custom/path/to/.env'
// }
});
console.log(config);
// output: { PORT: 3000, SENTRY: { ENABLED: false, DSN: 'something' } }
```
see [DotenvConfigOptions](https://github.com/dotenvx/dotenvx)
### Custom ajv instance
Optionally, the user can supply their own ajv instance:
```js
const envSchema = require('nested-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
### 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('nested-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('nested-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 'nested-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 `zod`:
```ts
import { envSchema } from 'nested-env-schema';
import { z } from 'zod/v4';
const schema = z.object({
PORT: z.number().default(3000),
});
type Schema = z.infer;
const config = envSchema({
schema: z.toJSONSchema(schema),
});
```
If no type is specified the `config` will have the `EnvSchemaData` type.
```ts
export type EnvSchemaData = {
[key: string]: unknown;
};
```
## Acknowledgements
Forked from https://github.com/fastify/env-schema
## License
MIT