A minimal, dependency-free TypeScript/JavaScript library for environment-variable loading and typed access.
npm install @sourceregistry/node-envenv 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(), .assert().
- 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.
---
``bash``
npm install @sourceregistry/node-env
---
`ts
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
---
If a key is absent, you can supply a default:
`ts`
const value = env.string("MISSING_KEY", "fallback");
---
The boolean logic treats "true" or "1" (case-insensitive) as true; anything else as false (unless default).
`ts`
process.env.FLAG = "1";
console.log(env.boolean("FLAG", false)); // => true
---
When you have many environment variables prefixed in a group:
`ts
// .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:
`ts`
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 }
---
A simple utility to select between two values based on the boolean state of an env key:
`ts`
const mode = env.utils.select("FEATURE_X", "enabled", "disabled");
---
| 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.url(key, default?)
| | Parse variable to URL object (or default(http://localhost)). |env.has(key)
| | Returns true if key exists in process.env. |env.assert([keys], error_builder?)
| | Throws an error if one or more keys doesn't 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:
`bash``
npm test
npm run test:coverage
---
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