node-env

🧰 @sourceregistry/node-env

What is it?

env makes it safe and simple to load variables from .env and process.env, and access them in a typed manner: strings, numbers, booleans, collections.
No dependencies, focus on runtime safety.

Key features:

Load .env file (ignores comments, blank lines, quotes) and merge into process.env.
Access variables via .string(), .number(), .boolean() with defaults.
Check keys with .has(), .defined().
Get env.dev boolean for “development vs production” mode.
Collect variables with a common prefix via .collection(), optional prefix removal & reviver.
Utility method .utils.select() for feature‐flag style branching.

Installation

npm install @sourceregistry/node-env

Usage

Basic

import { env } from "@sourceregistry/node-env";

console.log(env.string("APP_NAME", "MyApp"));       // => from .env or default
console.log(env.number("PORT", 3000));             // => number
console.log(env.boolean("DEBUG", false));          // => boolean

Suppose your .env file is:

APP_NAME=HelloWorld
PORT=8080
DEBUG=true

Then you’ll get:

HelloWorld
8080
true

Defaults

If a key is absent, you can supply a default:

const value = env.string("MISSING_KEY", "fallback");

Booleans

The boolean logic treats "true" or "1" (case-insensitive) as true; anything else as false (unless default).

process.env.FLAG = "1";
console.log(env.boolean("FLAG", false));  // => true

Collections

When you have many environment variables prefixed in a group:

// .env
API_URL=https://api.example.com
API_KEY=abcdef
API_TIMEOUT=5000

// code
const api = env.collection("API_");
console.log(api);
// => { URL: "https://api.example.com", KEY: "abcdef", TIMEOUT: "5000" }

You can remove the prefix and apply a reviver:

const cfg = env.collection("API_", {
  removePrefix: true,
  reviver: (value, key) => key === "TIMEOUT" ? Number(value) : value
});
console.log(cfg);
// => { URL: "https://api.example.com", KEY: "abcdef", TIMEOUT: 5000 }

Utility - select

A simple utility to select between two values based on the boolean state of an env key:

const mode = env.utils.select("FEATURE_X", "enabled", "disabled");

API Reference

Method	Description
`env.string(key, default?)`	Return the variable as a string (or default).
`env.number(key, default?)`	Parse variable to number (or default).
`env.boolean(key, default?)`	Parse variable to boolean (or default).
`env.has(key)`	Returns true if key exists in `process.env`.
`env.defined(key)`	Returns true if key exists and value is not `undefined`.
`env.dev`	Boolean flag: true if `NODE_ENV !== "production"`.
`env.collection(prefix, options?)`	Get an object of all env keys starting with `prefix`. Options include `removePrefix` and `reviver`.
`env.utils.select(key, TRUE, FALSE, predicate?)`	Return `TRUE` or `FALSE` depending on the predicate result on the env key.

🧪 Testing This library has 100% test coverage with Vitest:

npm test
npm run test:coverage

Contributing

Contributions are very welcome! Please open issues for bugs or feature requests and pull requests for changes. Follow the standard fork → branch → PR workflow.

🙌 Contributing PRs welcome! Please:

Add tests for new features
Maintain 100% coverage
Follow existing code style

Found a security issue? Report it responsibly.

🔗 GitHub: github.com/SourceRegistry/node-env
📦 npm: @sourceregistry/node-env