env-schema

library7.0.0jsnpmunverified

Validate environment variables against JSON Schema using Ajv with .env file support via Node.js built-in parseEnv. Version 7.0.0, actively maintained under Fastify organization. Key differentiators: leverages Node's native parseEnv (no dotenv dependency), supports custom Ajv instances and plugins, fluent-schema API, custom keywords like separator and expandEnv. Supports ESM and CJS, ships TypeScript types.

devops

npm install env-schema

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ENV-SCHEMA

env-schema

devopsjavascriptv7.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import envSchema from 'env-schema'

✗ import { envSchema } from 'env-schema'

Default export is the main function

default (CJS)

✓ const envSchema = require('env-schema')

✗ const { envSchema } = require('env-schema')

CJS uses default export as the whole module

EnvSchemaConfig

✓ import type { EnvSchemaConfig } from 'env-schema'

TypeScript type for the config object parameter

Defines a JSON schema for env vars with required PORT number, loads .env, outputs validated config.

import envSchema from 'env-schema'; const schema = { type: 'object', required: ['PORT'], properties: { PORT: { type: 'number', default: 3000 } } }; const config = envSchema({ schema: schema, dotenv: true }); console.log(config); // { PORT: 3000 }

Debug

Known issues

breakingVersion 7 drops support for dotenv package in favor of Node.js built-in parseEnv

fix

Remove dotenv dependency; .env files are now parsed using Node's parseEnv. The dotenv option still works but uses native parsing.

affects: >=7.0.0

breakingDefault export changed from object with main function to the function itself in v6+

fix

Use import envSchema from 'env-schema' instead of import { envSchema } from 'env-schema'

affects: >=6.0.0

deprecatedThe 'confKey' option is deprecated; use 'key' instead

fix

Replace confKey with key in the config object

affects: >=5.0.0

gotchaSchema does not allow additional properties by default (additionalProperties: false)

fix

Explicitly set additionalProperties: true in schema if needed

affects: >=1.0.0

gotchaCustom Ajv instance must include useDefaults, coerceTypes, and removeAdditional for expected behavior

fix

Pass { useDefaults: true, coerceTypes: true, removeAdditional: true } when creating custom Ajv instance

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'dotenv'

Version 7 removed dotenv dependency

fix

Upgrade env-schema to v7 and remove dotenv from your dependencies; use Node's built-in parseEnv automatically

TypeError: envSchema is not a function

Named import instead of default import before v6

fix

Use `import envSchema from 'env-schema'` (default import) or `const envSchema = require('env-schema')` for CJS

unexpected token u in JSON at position 0

Data passed to envSchema is not a valid JSON object (e.g., undefined)

fix

Ensure the data option is an object or omit it to use process.env

Upgrade

Version history

7.0.0latest on npm

Audit

Dependencies

ajvrequiredUsed for JSON schema validation of env variables

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/fastify/env-schema ↗

packageenv-schema ↗

homepagehttps://github.com/fastify/env-schema#readme ↗