dotenv-mono

Dotenv mono

If this project has helped you out, please support us with a star 🌟

📘 Description

What is this?

To prevent code duplication and enhance re-usability, a centralized configuration including all of your environment variables might be handy. Rather of generating a .env file for each package, we may utilize a single .env file at the project's root.

This is a package that allows monorepo applications and packages to share and load a centralized dotenv. It's based over dotenv package.

It also includes some extra features such as manipulation and saving of changes to the dotenv file.

The plugin dotenv-expand is enabled by default.

Structure Example

├── .env
├── packages
│   ├── ui-library
│   ├── other-library
├── apps
│   ├── web
│   ├── docs

How it works?

The package search the first .env file, matching with some priority criteria, by walking up the parent directories.

Priorities

Starting from the current process directory, this package finds the first file that matches the best filepath and filename criteria with the highest priority. The greater the depth of the up folder, the lesser its priority.

The priority can be customized on the configuration with the priorities property, see the example below on the usage section.

Note: The allowed values for NODE_ENV are usually test, development and production.

Priority	Filename
75	.env.$(NODE_ENV).local
50	.env.local
25	.env.$(NODE_ENV)
1	.env

Example

Given the following folder structure with dotenv files:

├── .env
├── .env.production
├── apps
│   ├── .env.development
│   ├── web
│   ├── docs
│   │   ├── .env
│   │   ├── .env.local

Having the following priority order:

Path	Priority	Depth
.env	1	2
.env.production	25	2
apps/.env.development	25	1
apps/docs/.env	1	0
apps/docs/.env.local	50	0

Then we will have the following outcome scenarios:

Current working directory	Env	Match
/	development	.env
/	production	.env.production
apps/web	development	.env
apps/web	development	apps/.env.development
apps/docs	development	apps/docs/.env.local

📖 Install

Install the library from npm or yarn just running one of the following command lines:

npm	yarn
npm install dotenv-mono --save	yarn add dotenv-mono

Install on Next.js

For custom advanced configuration of Next.js, you can create a next.config.js or next.config.mjs file in the root of your project directory (next to package.json).

Add the following line at the top of the file:

require("dotenv-mono").load();

Example

require("dotenv-mono").load();

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
	/* config options here */
};

module.exports = nextConfig;

💻 Usage

Load

Standard

require("dotenv-mono").load();

// or

const {dotenvLoad} = require("dotenv-mono");
dotenvLoad();

// or

import {dotenvLoad} from "dotenv-mono";
dotenvLoad();

Using the class

const {Dotenv} = require("dotenv-mono");
const dotenv = new Dotenv();
dotenv.load();

Having the output

If you want to have back directly the output like dotenv package.

require("dotenv-mono").config();

Load file with extension

// Use .dotenv.server or .dotenv.server.local, etc...
dotenvLoad({extension: "server"});

Load specific file

// You can specify the file path
dotenvLoad({path: "../../configs/.env"});

Load without dotenv-expand extension

dotenvLoad({expand: false});

Change priorities

// If .dotenv.overwrite is present use it with max priority
dotenvLoad({
	priorities: {
		".env.overwrite": 100,
	},
});

Make changes

const dotenv = new Dotenv();
dotenv.loadFile(); // Not loading into process
dotenv.save({
	"MY_ENV_1": "enjoy",
	"MY_ENV_2": "'enjoy quotes'",
	"MY_ENV_3": 999,
});

💡 Methods

Config

Setting	Description	Default
cwd	Specify the current working directory	process.cwd()
debug	Turn on/off logging to help debug why certain keys or values are not being set as you expect	false
depth	Specify the max depth to reach finding up the folder from the children directory	4
encoding	Specify the encoding of your file containing environment variables	utf8
expand	Turn on/off the dotenv-expand plugin	true
extension	Specify to load specific dotenv file used only on specific apps/packages (ex. .env.server...)
override	Override any environment variables that have already been set on your machine with values from your .env file	false
path	Specify a custom path if your file containing environment variables is located elsewhere
priorities	Specify the criteria of the filename priority to load as dotenv file	See Priorities

Methods

Load

It will read your .env file following the criteria, parse the contents, assign it to process.env.

public load(loadOnProcess: boolean): Dotenv;

LoadFile

It will read your .env file following the criteria, parse the contents, ready to be read or changed programmatically.

public loadFile(): Dotenv;

Save

Merge the data on input with the loaded data from load or loadFile, and save the changes on the original dotenv file.

public save(changes: Record<string, any>): Dotenv;

Parse

See the dotenv documentation HERE

public parse<T extends Record<string, any> = Record<string, any>>(src: string | Buffer): T;

🤔 How to contribute

Have an idea? Found a bug? Please raise to ISSUES or PULL REQUEST. Contributions are welcome and are greatly appreciated! Every little bit helps, and credit will always be given.

Changelog

1.1.2 (2022-11-18)

Bug Fixes

• add explicit typing on shortcut functions (2abe7ff)