dotenv-run is a collection of packages that use dotenv to support loading environment variables from .env files with multiple integrations.
Here are some of the benefits of using dotenv-run:
- ✅ Monorepo ✨: supports monorepo projects with multiple applications.
- ✅ Universal: supports multiple integrations including CLI, Webpack, Rollup, Vite, ESbuild and Angular.
- ✅ TypeScript: supports TS projects with type definitions for
process.envandimport.meta.env. - ✅ ESM: supports
process.envandimport.meta.envin ESM modules. - ✅ Secure: supports filtering environment variables by prefix.
| Integration | Package | Status |
|---|---|---|
| CLI | @dotenv-run/cli | ✅ |
| Core | @dotenv-run/core | ✅ |
| ESBuild | @dotenv-run/esbuild | ✅ |
| Rollup | @dotenv-run/rollup | ✅ |
| Vite | @dotenv-run/rollup | ✅ |
| Node.js preload | @dotenv-run/load | ✅ |
| Angular | @ngx-env/builder | ✅ |
Assuming you have the following monorepo structure:
platform
├── apps
│ ├── vite-app
│ ├── ng-app
│ └── esbuild-app
│ │ ├── .env.local # API_BASE=http://localhost:3001
│ │ ├── package.json
│ │ └── webapp.config.mjs
├── libs
│ └── rollup-lib
│ ├── package.json
│ └── rollup.config.mjs
├── .env.dev # API_BASE=https://dev.dotenv.run
├── .env.prod # API_BASE=https://prod.dotenv.run
├── .env # API_USERS=$API_BASE/api/v1/users;API_AUTH=https://$API_BASE/auth
├── nx.json
└── package.jsonand the following dotenv-run options:
{
"verbose": true, // print debug information
"unsecure": true, // display environment variables values
"root": "../..", // root directory to search for .env files
"environment": "dev", // environment to load (default: NODE_ENV)
"files": [".env"], // .env files to load (default: .env)
"prefix": "^API_" // prefix to filter environment variables (used with bundlers)
}dotenv-run will search and load .env.* files located in the root workspace /home/code/platform down to the current working directory of the application.
- Root directory: /home/code/platform
- Working directory: /codes/code/platform/apps/esbuild-app
- Files: .env
- Environment: dev
- Environment files:
✔ /home/code/platform/apps/esbuild-app/.env.local
✔ /home/code/platform/.env.dev
✔ /home/code/platform/.env
- Environment variables: API (Unsecure Mode)
✔ API_USERS http://localhost:3001/api/v1/users
✔ API_AUTH https://localhost:3001/auth@dotenv-run/cli is a standalone CLI that can be used to run a script.
❯ npx dotenv-run
Usage: dotenv-run [options] -- <command>
Options:
-v, --verbose [regexp] display debug information
-u, --unsecure display environment variables values
-e, --env [environment] environment to load (default: NODE_ENV)
-r, --root root directory to search for .env files
-f, --file [.env,.secrets] .env files to load (default: .env)
-h, --help output usage information
Examples:
dotenv-run -d
dotenv-run -- npm start
dotenv-run -r ../.. -f .env,.secrets -- npm start
dotenv-run -f ../.env,../.env.api -- npm start@dotenv-run/core is the core package that can be used to load environment variables from .env files.
env({
root: "../..",
verbose: true,
prefix: "^API_",
files: [".env"],
});@dotenv-run/esbuild is a plugin for esbuild that can be used to inject environment variables into your applications.
import { dotenvRun } from "@dotenv-run/esbuild";
await build({
write: false,
bundle: true,
entryPoints: [`test/app.js`],
plugins: [
dotenvRun({
verbose: true,
root: "../../",
prefix: "^API",
}),
],
});@ngx-env/builder is a plugin for Angular CLI and a wrapper around @dotenv-run/esbuild or @dotenv-run/webpack that can be used to inject environment variables into your Angular applications.
- ✅ Official recommendation in dotenv documentation 🔥
- ✅ Runtime environment variables (Experimental) 🎉
- ✅ Webpack and ESBuild support 🚀
- ✅ Easy to use, no configuration required
- ✅ Up to date with latest Angular versions
- ✅ Supports all Angular CLI commands
- ✅ Used by popular repositories
- ✅ Active development and support
ng add @ngx-env/builderEnvironment variables should start with NG_APP_ prefix, you can define a custom prefix.
NG_APP_VERSION=$npm_package_version
NG_APP_COMMIT=$GITHUB_SHA
NG_APP_ENABLE_SENTRY=false@Component({
selector: "app-footer",
template: `{{ branch }} - {{ commit }}`,
standalone: true,
})
export class MainComponent {
branch = import.meta.env.NG_APP_BRANCH_NAME; // Recommended
commit = process.env.NG_APP_COMMIT; // Deprecated
}<!-- index.html -->
<head>
<title>NgApp on %NG_APP_BRANCH_NAME% - %NG_APP_COMMIT%</title>
</head>Configuration options can be passed to @ngx-env/builder using ngxEnv section in angular.json file.
{
"builder": "@ngx-env/builder:application",
"options": {
"ngxEnv": {
"verbose": true,
"root": "../..",
"prefix": "^NG_APP_"
}
}
}If you want to update the environment variables at runtime, you can use the runtime option.
You can find the full @ngx-env/builder documentation here.
@dotenv-run/webpack is a plugin for webpack that can be used to inject environment variables into your applications.
import { DotenvRunPlugin } from "@dotenv-run/webpack";
import path from "path";
const __dirname = path.resolve();
export default {
entry: "./src/index.js",
output: {
filename: "main.js",
path: path.resolve(__dirname, "dist"),
},
plugins: [
new DotenvRunPlugin(
{ prefix: "^API", verbose: true, root: "../.." },
__dirname
),
],
};@dotenv-run/rollup is a plugin for rollup that can be used to inject environment variables into your applications.
import env from "@dotenv-run/rollup";
export default {
input: "src/index.js",
output: {
file: "dist/index.js",
},
plugins: [env({ prefix: "API", verbose: true, root: "../../.." })],
};MIT © Chihab Otmani
