@tuki0918/zodenv

@tuki0918/zodenv is a very lightweight, type-safe environment variable library using Zod.

Installation

npm install @tuki0918/zodenv

Usage (Node)

.env

NODE_ENV="development"
PORT="3000"
SAMPLE_RATE="0.5"
BOOLEAN_FLAG="true"
__OTHER__="__other__"

code

import { zenv } from "@tuki0918/zodenv";

const schema = zenv.object({
    NODE_ENV: zenv.enum(["development", "production", "test"]),
    PORT: zenv.int(),
    SAMPLE_RATE: zenv.number(),
    BOOLEAN_FLAG: zenv.boolean(),
    OPTIONAL_VAR: zenv.string().optional(),
});

const ENV = zenv.validate(schema);
// NODE_ENV: "development" (string)
// PORT: 3000 (number)
// SAMPLE_RATE: 0.5 (number)
// BOOLEAN_FLAG: true (boolean)
// OPTIONAL_VAR: undefined

// Cannot assign to 'NODE_ENV' because it is a read-only property.
// ENV.NODE_ENV = "production"

Usage (Next.js)

.env

NEXT_PUBLIC_MY_VALUE="abc"
MY_SECRET="xyz"

utils/dotenv.public.ts

import { zenv } from "@tuki0918/zodenv";

export const schema = zenv.object({
    NEXT_PUBLIC_MY_VALUE: zenv.string(),
});

export const ENV = zenv.validate(schema, {
    NEXT_PUBLIC_MY_VALUE: process.env.NEXT_PUBLIC_MY_VALUE,
});
// NEXT_PUBLIC_MY_VALUE: "abc"

utils/dotenv.ts

import { zenv } from "@tuki0918/zodenv";
import { schema as publicSchema } from "@/utils/dotenv.public";

const schema = zenv.object({
    MY_SECRET: zenv.string(),
});

export const ENV = zenv.validate(publicSchema.merge(schema));
// NEXT_PUBLIC_MY_VALUE: "abc"
// MY_SECRET: "xyz"

(optional) instrumentation.ts

You can enforce environment variable checks when starting the Next.js server.

import "@/utils/dotenv";

Custom Helpers

| Method | Description | undefined | empty | and error | | ---- | ---- | ---- | ---- | ---- | | object | Alias for z.object | _ | _ | _ | | enum | Alias for z.enum | ❌️ | ❌️ | invalid text | | string | Alias for z.string | ❌️ | ✅️ | _ | | number | Converts to a number. | ❌️ | ❌️ | invalid number | | int | Converts to an integer. Accepts signed integer strings only. Rejects decimals, exponent notation, and non-decimal formats. | ❌️ | ❌️ | invalid number | | boolean | Converts to a boolean. Uses Zod v4 stringbool defaults. (TRUE: true, 1, yes, on, y, enabled / FALSE: false, 0, no, off, n, disabled) | ❌️ | ❌️ | invalid value |

Tests

npm test

License

MIT License