env-guard

env-guard is a small TypeScript-first environment validator for Node.js, Next.js, and backend services. It is built for the place where production crashes usually start: missing vars, broken coercion, and unreadable startup errors.

What it does

• Defines env vars with typed schema helpers.
• Coerces strings into numbers, booleans, and URLs.
• Supports required, optional, and defaulted vars.
• Separates server, client, and shared groups.
• Produces readable startup errors with secret masking.
• Generates .env.example files.
• Exports JSON schema for tooling.
• Provides Express, Fastify, and Next.js integration helpers.

Install

npm install @theartificialdev/env-guard

Quick start

import {
  apiKey,
  boolean,
  databaseUrl,
  defineEnv,
  generateEnvExample,
  port,
  toJsonSchema,
  url,
} from 'env-guard';

const envDefinition = {
  server: {
    PORT: port().default(3000),
    DATABASE_URL: databaseUrl(),
    FEATURE_FLAG: boolean().default(false),
    API_KEY: apiKey(),
  },
  client: {
    NEXT_PUBLIC_API_BASE: url(),
  },
} as const;

export const env = defineEnv(envDefinition, {
  runtimeEnv: process.env,
});

export const example = generateEnvExample(envDefinition);
export const schema = toJsonSchema(envDefinition);

API shape

The main entry point is defineEnv(definition, options), where definition is grouped into server, client, and shared sections.

Supported builders:

• string()
• number()
• boolean()
• url()
• enumValue()
• custom()
• port()
• databaseUrl()
• apiKey()

Validation behavior

defineEnv throws EnvValidationError when validation fails. The error groups issues by section and masks secret values before they hit logs.

Example output:

env-guard validation failed with 2 issues.

server:
  - PORT: must be an integer
  - DATABASE_URL: is required but missing

Example generation

import { generateEnvExample } from 'env-guard';

const envFile = generateEnvExample(envDefinition, {
  title: 'My app environment',
});

This produces a ready-to-commit .env.example with grouped sections, default values, descriptions, and secret placeholders.

JSON schema export

import { toJsonSchema } from 'env-guard';

const jsonSchema = toJsonSchema(envDefinition, { grouped: true });

The schema can be used for editor tooling, config validation, or documentation generation.

Adapters

Express

import { createExpressEnvMiddleware } from 'env-guard';

const { env, middleware } = createExpressEnvMiddleware(envDefinition, {
  runtimeEnv: process.env,
});

app.use(middleware);

Fastify

import { createFastifyEnvPlugin } from 'env-guard';

const { env, plugin } = createFastifyEnvPlugin(envDefinition, {
  runtimeEnv: process.env,
});

fastify.register(plugin);

Next.js

import { createNextEnv } from 'env-guard';

const nextEnv = createNextEnv(envDefinition, {
  runtimeEnv: process.env,
});

export default nextEnv.withNextConfig({});

The client group is what gets forwarded to next.config.js.

CI validation command

Add this to your package scripts:

{
  "scripts": {
    "validate": "npm run typecheck && npm run test && npm run build"
  }
}

That gives you a single publication gate that checks types, runtime behavior, and the build artifact.

Publishing checklist

• npm run validate
• Review the generated dist/ output
• Confirm the package name and version in package.json
• Publish with npm publish