# dotenv-defaults

> dotenv... but with defaults!

Latest version **6.0.0** (published 2026-02-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install dotenv-defaults
pnpm add dotenv-defaults
yarn add dotenv-defaults
bun add dotenv-defaults
```

## Health

**Score 60/100 (C)** — status: stable.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 6.0.0 |
| Published | 2026-02-02 |
| First published | 2018-04-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 1 |
| Unpacked size | 10.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 80 |
| Author | Matt Steele |
| Maintainers | mrsteele |
| Keywords | dotenv, defaults, extension, env, default, fallback |

## Links

- npm: https://www.npmjs.com/package/dotenv-defaults
- Repository: https://github.com/mrsteele/dotenv-defaults
- Homepage: https://github.com/mrsteele/dotenv-defaults#readme
- Issues: https://github.com/mrsteele/dotenv-defaults/issues
- npm.io page: https://npm.io/package/dotenv-defaults

## Dependencies (1)

- [dotenv](https://npm.io/package/dotenv.md) ^16.4.7

## 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

- 6.0.0 (latest) — 2026-02-02
- 5.0.2 — 2022-06-27
- 5.0.1 — 2022-06-27
- 5.0.0 — 2022-01-17
- 3.0.2 — 2022-01-17
- 4.0.0 — 2022-01-17
- 3.0.1 — 2022-01-17
- 3.0.0 — 2021-09-17
- 2.0.2 — 2021-06-03
- 2.0.1 — 2020-08-20
- 2.0.0 — 2020-06-22
- 1.1.1 — 2020-01-22
- 1.1.0 — 2020-01-21
- 1.0.3 — 2019-12-18
- 1.0.2 — 2019-01-12
- … 3 more at https://npm.io/package/dotenv-defaults/versions

## README

# dotenv-defaults

A dotenv system that supports defaults.

### Status

![npm](https://img.shields.io/npm/v/dotenv-defaults.svg)
[![Main](https://github.com/mrsteele/dotenv-defaults/actions/workflows/main.yml/badge.svg)](https://github.com/mrsteele/dotenv-defaults/actions/workflows/main.yml)
[![dotenv-vault](https://badge.dotenv.org/works-with.svg?r=3)](https://www.dotenv.org/get-started?r=3)

### Installation

Use the following to install this module:

```
npm i dotenv-defaults --save
```

### Usage

This module supports all the features from the original [dotenv](https://www.npmjs.com/package/dotenv) module, so usage should be simple enough:

```
# .env.defaults, safe to commit
HOST=website.com
EMAIL=test@email.com
```

```
# .env, DO NOT COMMIT
HOST=mrsteele.dev
```

The result

```js
// ESM (Node.js 18+)
import { config } from 'dotenv-defaults'
config()

// Or load it directly like this
import 'dotenv-defaults/config'

console.log(process.env.HOST)
// Outputs: mrsteele.dev

console.log(process.env.EMAIL)
// Outputs: test@email.com
```

##### TypeScript
This module now includes full TypeScript type definitions and works seamlessly with TypeScript:

```typescript
import { config, parse, type ConfigOptions } from 'dotenv-defaults'

// Or load directly
import 'dotenv-defaults/config'

const options: ConfigOptions = {
  path: './.env',
  defaults: './.env.defaults'
}

config(options)
```

##### CLI
You can also call this module directly when using the node executable.
So, for example if you are running a custom script with node and you want to load your environment variables you can do the following `node --import dotenv-defaults/config your-script.js`. (_When using this method, please make sure that you have installed dotenv-defaults with npm or yarn in the same directory_)

> **Note:** For Node.js versions that don't support `--import`, you can use `node --loader dotenv-defaults/config your-script.js`

### Differences

The only thing to note is that the original module supported an `options` argument in the `config` function.

This module supports that as well, but there is an added `defaults` property that can allow you to define where that file is located. An example is shown below:

```js
// ESM
import { config } from 'dotenv-defaults'

// all of these are the default values...
config({
  path: './.env',
  encoding: 'utf8',
  defaults: './.env.defaults' // This is new
})
```

### License

MIT

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