<commit_before># dotenv-safe

Identical to [`dotenv`](https://github.com/motdotla/dotenv), but ensures that
all necessary environment variables are defined after reading from `.env`.
These needed variables are read from `.env.example`, which should be commited
along with your project.

# Installation

```
npm install --save dotenv-safe
```

# Usage

Requiring and loading is identical:

```js
require('dotenv-safe').load();
```

This will load environment variables from `.env` as usual, but will also read
any variables defined in `.env.example`. If any variables are missing from
`.env`, an exception listing them will be thrown. Otherwise, returns `true`.

`dotenv-safe` compares the actual environment after loading `.env` with the
example file, so it will work correctly if environment variables are missing
in the `.env` but provided through other means such as a shell script.

You can use `.env.example`, `.env.sample` or provide a different filename:

```js
require('dotenv-safe').load({sample: './.my-env-sample-filename'});
```


# Example

```dosini
# .env, private
SECRET=topsecret
```

```dosini
# .env.example, commited to repo
SECRET=
TOKEN=
KEY=
```

```js
require('dotenv-safe').load();
```

Since the provided `.env` file does not contain all the variables defined in
`.env.example`, an exception is thrown:

```
Error: Missing environment variables: TOKEN, KEY
```



# Options

[Same options and methods supported by `dotenv`](https://github.com/motdotla/dotenv#options).

# Motivation

I regularly use apps that depend on `.env` files but don't validate if all
the necessary variables have been defined correctly.
Instead of having to document and validate this manually, I prefer to commit
a sample `.env` file (no values, key names only) which can be used as a
reference.<commit_msg>Swap example and usage order in readme<commit_after># dotenv-safe

Identical to [`dotenv`](https://github.com/motdotla/dotenv), but ensures that
all necessary environment variables are defined after reading from `.env`.
These needed variables are read from `.env.example`, which should be commited
along with your project.

# Installation

```
npm install --save dotenv-safe
```

# Example

```dosini
# .env, private
SECRET=topsecret
```

```dosini
# .env.example, commited to repo
SECRET=
TOKEN=
KEY=
```

```js
require('dotenv-safe').load();
```

Since the provided `.env` file does not contain all the variables defined in
`.env.example`, an exception is thrown:

```
Error: Missing environment variables: TOKEN, KEY
```

# Usage

Requiring and loading is identical:

```js
require('dotenv-safe').load();
```

This will load environment variables from `.env` as usual, but will also read
any variables defined in `.env.example`. If any variables are missing from
`.env`, an exception listing them will be thrown. Otherwise, returns `true`.

`dotenv-safe` compares the actual environment after loading `.env` with the
example file, so it will work correctly if environment variables are missing
in the `.env` but provided through other means such as a shell script.

You can use `.env.example`, `.env.sample` or provide a different filename:

```js
require('dotenv-safe').load({sample: './.my-env-sample-filename'});
```

# Options

[Same options and methods supported by `dotenv`](https://github.com/motdotla/dotenv#options).

# Motivation

I regularly use apps that depend on `.env` files but don't validate if all
the necessary variables have been defined correctly.
Instead of having to document and validate this manually, I prefer to commit
a sample `.env` file (no values, key names only) which can be used as a
reference.
{'fraction_non_alphanumeric': 0.11318681318681319, 'fraction_numerical': 0.0, 'mean_word_length': 4.618827160493828, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '57027', 'n_tokens_mistral': 1069, 'n_tokens_neox': 1019, 'n_words': 459}