# populate-env

> Populate a given object from process.env with default value and types.

Latest version **2.6.1** (published 2026-06-14) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install populate-env
pnpm add populate-env
yarn add populate-env
bun add populate-env
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.6.1 |
| Published | 2026-06-14 |
| First published | 2022-02-26 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 13.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Beeno Tung |
| Maintainers | beenotung |
| Keywords | env, environment, variable, typescript |

## Links

- npm: https://www.npmjs.com/package/populate-env
- Repository: https://github.com/beenotung/populate-env
- Homepage: https://github.com/beenotung/populate-env#readme
- Issues: https://github.com/beenotung/populate-env/issues
- npm.io page: https://npm.io/package/populate-env

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads

## Recent versions

- 2.6.1 (latest) — 2026-06-14
- 2.6.0 — 2026-06-14
- 2.5.0 — 2026-06-14
- 2.4.3 — 2025-03-07
- 2.4.2 — 2025-03-07
- 2.4.1 — 2025-03-07
- 2.4.0 — 2025-03-07
- 2.3.1 — 2024-11-07
- 2.3.0 — 2024-09-05
- 2.2.0 — 2024-09-05
- 2.1.1 — 2024-08-26
- 2.1.0 — 2024-04-19
- 2.0.0 — 2022-03-09
- 1.0.2 — 2022-03-01
- 1.0.1 — 2022-02-26
- … 1 more at https://npm.io/package/populate-env/versions

## README

# populate-env

Populate a given object from process.env with default value and types.

[![npm Package Version](https://img.shields.io/npm/v/populate-env.svg)](https://www.npmjs.com/package/populate-env)

## Usage Example

```typescript
// using named import
import { populateEnv } from 'populate-env'

// or using default import
// import populateEnv from 'populate-env'

// with auto inferred type
export let env = {
  JWT_SECRET: '', // mandatory string variable
  HOST: '0.0.0.0', // optional string variable
  VERSION: 0, // mandatory numeric variable
  PORT: 8100, // optional numeric variable
  SOME_MORE_VAR: '',
}

populateEnv(env) // will throw error if missed

populateEnv(env, 'halt') // halt with clear error message
// print to stderr: "Missing JWT_SECRET, SOME_MORE_VAR in env"
// then auto halt with process.exit(1)
```

## Typescript Signature

```typescript
export default populateEnv

export function populateEnv(
  env: Record<string, string | number>,
  options?: PopulateEnvOptions,
): void

export type PopulateEnvOptions = {
  mode?: 'halt' | 'error' // default is 'error'
  source?: typeof process.env // default is process.env
  auto_load?: boolean // if true, will resolve the env file using getEnvFile(), and load it into source
}

export class EnvError extends Error {
  missingNames: string[]
}

/**
 * @throws {TypeError} if value is not a valid boolean and defaultValue is not provided
 */
export function toBoolean(value: string, defaultValue?: boolean): boolean

/**
 * @description you can add custom mapping here.
 * @default on/off, true/false, yes/no, enable/disable, enabled/disabled
 */
export let boolean_values: Record<string, boolean>

/** save mentioned (subset of) env variables to file */
export function appendEnv<
  T extends object,
  K extends keyof T & string,
>(options: {
  env: T
  /** @default '.env' */
  file?: string
  key: K | K[]
}): void

/** save entire env to file */
export function saveEnv(options: {
  env: object
  /** @default '.env' */
  file?: string
}): void

/**
 * Resolve env file from `process.env.ENV_FILE` if set.
 * Otherwise return the first existing file among `.env.{mode}`, `.{mode}.env`, `{mode}.env`
 * for the mode (use `process.env.NODE_ENV` if set, or `development` then `dev` then `local` when unset).
 * Finally return `.env` if it exists.
 * If no file is found, return null.
 */
export function getEnvFile(): string | null
```

## License

This project is licensed with [BSD-2-Clause](./LICENSE)

This is free, libre, and open-source software. It comes down to four essential freedoms [[ref]](https://seirdy.one/2021/01/27/whatsapp-and-the-domestication-of-users.html#fnref:2):

- The freedom to run the program as you wish, for any purpose
- The freedom to study how the program works, and change it so it does your computing as you wish
- The freedom to redistribute copies so you can help others
- The freedom to distribute copies of your modified versions to others

---
_Source: https://npm.io/package/populate-env · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._