{"id":19425455,"url":"https://github.com/marcocesarato/dotenv-mono","last_synced_at":"2025-05-09T01:42:50.897Z","repository":{"id":63057268,"uuid":"564277117","full_name":"marcocesarato/dotenv-mono","owner":"marcocesarato","description":"This package permit to have a centralized dotenv on a monorepo.  It also includes some extra features such as manipulation and saving of changes to the dotenv file, a default centralized file, and a file loader with ordering and priorities.","archived":false,"fork":false,"pushed_at":"2024-04-17T13:33:05.000Z","size":674,"stargazers_count":41,"open_issues_count":8,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-09T17:52:24.683Z","etag":null,"topics":["defaults","development","dotenv","dotenv-expand","edit","env","environment","local","mono","monorepo","nextjs","node","nodejs","packages","production","shared","storybook","test","turbo","turborepo"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcocesarato.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-10T11:24:11.000Z","updated_at":"2024-11-07T00:44:16.000Z","dependencies_parsed_at":"2023-12-02T06:23:04.248Z","dependency_job_id":"24353815-6291-48a8-bc58-f642d3e14f05","html_url":"https://github.com/marcocesarato/dotenv-mono","commit_stats":{"total_commits":214,"total_committers":11,"mean_commits":"19.454545454545453","dds":0.2850467289719626,"last_synced_commit":"e7a66702823dc9e0b264a2929335a32e9d50748d"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcocesarato%2Fdotenv-mono","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcocesarato%2Fdotenv-mono/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcocesarato%2Fdotenv-mono/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcocesarato%2Fdotenv-mono/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcocesarato","download_url":"https://codeload.github.com/marcocesarato/dotenv-mono/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224742526,"owners_count":17362232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defaults","development","dotenv","dotenv-expand","edit","env","environment","local","mono","monorepo","nextjs","node","nodejs","packages","production","shared","storybook","test","turbo","turborepo"],"created_at":"2024-11-10T14:03:31.169Z","updated_at":"2024-11-18T02:04:04.509Z","avatar_url":"https://github.com/marcocesarato.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Dotenv mono\n\n### If this project has helped you out, please support us with a star 🌟\n\n\u003cbr\u003e\n\n[![NPM version](http://img.shields.io/npm/v/dotenv-mono.svg?style=for-the-badge)](http://npmjs.org/package/dotenv-mono)\n[![js-prettier-style](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=for-the-badge)](https://prettier.io/)\n\n\u003c!--[![Package Quality](https://npm.packagequality.com/shield/dotenv-mono.svg?style=for-the-badge)](https://packagequality.com/#?package=dotenv-mono)--\u003e\n\n\u003c/div\u003e\n\n## 📘 Description\n\n#### What is this?\n\nTo prevent code duplication and enhance re-usability, a centralized configuration including all of your environment variables might be handy.\nRather of generating a `.env` file for each package, we may utilize a single `.env` file at the project's root.\n\nThis is a package that allows monorepo applications and packages to share and load a centralized dotenv.\nIt's based over [dotenv](https://github.com/motdotla/dotenv) package.\n\nIt also includes some extra features such as manipulation and saving of changes to the dotenv file, a default centralized file, and a file loader with ordering and priorities.\n\nThe plugin [dotenv-expand](https://www.npmjs.com/package/dotenv-expand) is enabled by default.\n\n##### Structure Example\n\n```text\n├── .env\n├── .env.production\n├── .env.defaults\n├── packages\n│   ├── ui-library\n│   ├── other-library\n├── apps\n│   ├── web\n│   │   ├── .storybook\n│   ├── docs\n```\n\n#### How it works?\n\nThe package search the first `.env` file, matching with some priority criteria, by walking up the parent directories.\n\n##### Priorities\n\nStarting from the current process directory, this package finds the first file that matches the best filepath and filename criteria with the highest priority.\nThe greater the depth of the up folder, the lesser its priority.\n\nThe priority can be customized on the configuration with the `priorities` property, see the example below on\nthe [usage](#change-priorities) section.\n\n\u003e Note: The allowed values for `NODE_ENV` are usually `test`, `development` and `production`.\n\n| Priority | Filename                 |\n| -------- | ------------------------ |\n| 75       | `.env.$(NODE_ENV).local` |\n| 50       | `.env.local`             |\n| 25       | `.env.$(NODE_ENV)`       |\n| 1        | `.env`                   |\n\n###### Example\n\nGiven the following folder structure with dotenv files:\n\n```text\n├── .env\n├── .env.production\n├── apps\n│   ├── .env.development\n│   ├── web\n│   ├── docs\n│   │   ├── .env\n│   │   ├── .env.local\n```\n\nHaving the following priority order:\n\n| Path                    | Priority | Depth |\n| ----------------------- | -------- | ----- |\n| `.env`                  | 1        | 2     |\n| `.env.production`       | 25       | 2     |\n| `apps/.env.development` | 25       | 1     |\n| `apps/docs/.env`        | 1        | 0     |\n| `apps/docs/.env.local`  | 50       | 0     |\n\nThen we will have the following outcome scenarios:\n\n| Current working directory | Env           | Match                   |\n| ------------------------- | ------------- | ----------------------- |\n| `/`                       | `development` | `.env`                  |\n| `/`                       | `production`  | `.env.production`       |\n| `apps/web`                | `development` | `.env`                  |\n| `apps/web`                | `development` | `apps/.env.development` |\n| `apps/docs`               | `development` | `apps/docs/.env.local`  |\n\n## 📖 Install\n\nInstall the library from npm or yarn just running one of the following command lines:\n\n| npm                              | yarn                   |\n| -------------------------------- | ---------------------- |\n| `npm install dotenv-mono --save` | `yarn add dotenv-mono` |\n\n### Install on Next.js\n\nFor custom advanced configuration of Next.js, you can create a `next.config.js` or `next.config.mjs` file in the root of\nyour project directory (next to `package.json`).\n\nAdd the following line at the top of the file:\n\n```js\nrequire(\"dotenv-mono\").load();\n```\n\n###### Example\n\n```js\nrequire(\"dotenv-mono\").load();\n\n/**\n * @type {import('next').NextConfig}\n */\nconst nextConfig = {\n\t/* config options here */\n};\n\nmodule.exports = nextConfig;\n```\n\n### Install on Storybook\n\nThe main configuration file is `.storybook/main.js`. This file controls the Storybook server's behavior, so you must restart Storybook’s process when you change it.\n\nAdd the following lines on the file:\n\n```js\nconst dotenv = require(\"dotenv-mono\").load();\n\nconst config = {\n\t/* config options here */\n\tenv: (config) =\u003e {\n\t\treturn {\n\t\t\t...config,\n\t\t\t...dotenv.env,\n\t\t};\n\t},\n};\n\nmodule.exports = config;\n```\n\n## 💻 Usage\n\n### Load\n\nSimple methods to export environment variables from the dotenv into the working process.\nHere are several potential implementation approaches based on your preferences.\n\n```js\n// Inline\nrequire(\"dotenv-mono\").load(/* config */);\n\n// Using the function\nconst {dotenvLoad} = require(\"dotenv-mono\");\ndotenvLoad(/* config */);\n\n// Using import\nimport {dotenvLoad} from \"dotenv-mono\";\nconst dotenv = dotenvLoad(); // Dotenv instance\n\n// Using the class\nconst {Dotenv} = require(\"dotenv-mono\");\nconst dotenv = new Dotenv(/* config */);\ndotenv.load();\n```\n\n#### Having the dotenv output\n\nIf you need a fast way to replace [dotenv](https://github.com/motdotla/dotenv) package with **dotenv-mono**, and you need also to have a retro-compatible feature, you can have back directly the output like [dotenv](https://github.com/motdotla/dotenv) package using the `config` method.\n\n```js\n// Inline\nconst output = require(\"dotenv-mono\").config(/* config */);\n\n// Using the function\nconst {dotenvConfig} = require(\"dotenv-mono\");\nconst output = dotenvConfig(/* config */);\n```\n\n### Load file with extension\n\n```js\n// Use `.dotenv.server` or `.dotenv.server.local`, etc...\nload({extension: \"server\"});\n```\n\n### Load specific file\n\n```js\n// You can specify the file path\nload({path: \"../../configs/.env\"});\n```\n\n### Load without [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand) extension\n\n```js\nload({expand: false});\n```\n\n### Change default filename\n\n```js\nload({defaults: \".env.def\"});\n```\n\n### Change priorities\n\n```js\n// If `.dotenv.overwrite` is present use it with max priority\nload({\n\tpriorities: {\n\t\t\".env.overwrite\": 100,\n\t},\n});\n```\n\n### Make changes\n\n```js\nconst dotenv = require(\"dotenv-mono\").load();\ndotenv.save({\"MY_ENV_1\": \"enjoy\"});\n\n// Without loading into the working process\nconst {Dotenv} = require(\"dotenv-mono\");\nconst dotenv = new Dotenv();\ndotenv.loadFile(); // Skip loading into the process\ndotenv.save({\n\t\"MY_ENV_1\": \"enjoy\",\n\t\"MY_ENV_2\": \"'enjoy quotes'\",\n\t\"MY_ENV_3\": 999,\n});\n```\n\n### Preload\n\nAs on the [dotenv](https://github.com/motdotla/dotenv) package on the CLI/Console, you can use the `--require` (`-r`) [command line option](https://nodejs.org/api/cli.html#-r---require-module) to preload dotenv. By doing this, you do not need to require and load dotenv in your application code.\n\n```bash\n$ node -r dotenv-mono/load your_script.js\n```\n\nThe configuration options below are supported as command line arguments in the format `dotenv_config_\u003coption\u003e=value`\n\n```bash\n$ node -r dotenv-mono/load your_script.js dotenv_config_path=/custom/path/to/.env dotenv_config_debug=true\n```\n\nAdditionally, you can use environment variables to set configuration options. Command line arguments will precede these.\n\n```bash\n$ DOTENV_CONFIG_\u003cOPTION\u003e=value node -r dotenv-mono/load your_script.js\n```\n\n```bash\n$ DOTENV_CONFIG_ENCODING=latin1 DOTENV_CONFIG_DEBUG=true node -r dotenv-mono/load your_script.js dotenv_config_path=/custom/path/to/.env\n```\n\n## 💡 Methods\n\n### Config\n\n| Setting      | Description                                                                                                     | Default                       |\n| ------------ | --------------------------------------------------------------------------------------------------------------- | ----------------------------- |\n| `cwd`        | Specify the current working directory                                                                           | `process.cwd()`               |\n| `debug`      | Turn on/off logging to help debug why certain keys or values are not being set as you expect                    | `false`                       |\n| `defaults`   | Specify the defaults dotenv filename (it **can't** override any environment variables)                          | `.env.defaults`               |\n| `depth`      | Specify the max depth to reach finding up the folder from the children directory                                | `4`                           |\n| `encoding`   | Specify the encoding of your file containing environment variables                                              | `utf8`                        |\n| `expand`     | Turn on/off the [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand) plugin                           | `true`                        |\n| `extension`  | Specify to load specific dotenv file used only on specific apps/packages (ex. `.env.server...`)                 |                               |\n| `override`   | Override any environment variables that have already been set on your machine with values from your `.env` file | `false`                       |\n| `path`       | Specify a custom path if your file containing environment variables is located elsewhere                        |                               |\n| `priorities` | Specify the criteria of the filename priority to load as dotenv file                                            | See [Priorities](#priorities) |\n\n### Dotenv Methods\n\n#### Load Environments\n\nIt will read your `.env` file following the criteria, parse the contents, assign it to `process.env`.\n\n\u003e Note: This method differs from the previous `load` **function**.\n\u003e In that it requires the configuration to be loaded on the class instance via the constructor.\n\n```\npublic load(loadOnProcess: boolean): Dotenv;\n```\n\n#### Load File\n\nIt will read your `.env` file following the criteria, parse the contents, ready to be read or changed programmatically.\n\n```\npublic loadFile(): Dotenv;\n```\n\n#### Save\n\nMerge the data on input with the loaded data from `load` or `loadFile`, and save the changes on the original dotenv file.\n\n\u003e Note: If `.env.defaults` is present, it won't be overwritten, you can just save the changes on the main dotenv file (`.env`, `.env.local`, etc...)\n\n```\npublic save(changes: Record\u003cstring, any\u003e): Dotenv;\n```\n\n#### Parse\n\nSee the [dotenv](https://github.com/motdotla/dotenv) documentation [HERE](https://github.com/motdotla/dotenv#parse)\n\n```\npublic parse\u003cT extends Record\u003cstring, any\u003e = Record\u003cstring, any\u003e\u003e(src: string | Buffer): T;\n```\n\n## 🤔 How to contribute\n\nHave an idea? Found a bug? Please raise to [ISSUES](https://github.com/marcocesarato/dotenv-mono/issues)\nor [PULL REQUEST](https://github.com/marcocesarato/dotenv-mono/pulls).\nContributions are welcome and are greatly appreciated! Every little bit helps, and credit will always be given.\n\n\u003cp align=\"center\"\u003e\n    \u003cbr\u003e\n    \u003ca href=\"https://nodei.co/npm/dotenv-mono/\" rel=\"nofollow\"\u003e\n        \u003cimg align=\"center\" src=\"https://nodei.co/npm/dotenv-mono.png?downloads=true\u0026downloadRank=true\" width=\"384\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcocesarato%2Fdotenv-mono","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcocesarato%2Fdotenv-mono","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcocesarato%2Fdotenv-mono/lists"}