🧰 @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