dotenv-run

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.env and import.meta.env.
• ✅ ESM: supports process.env and import.meta.env in ESM modules.
• ✅ Secure: supports filtering environment variables by prefix.

Integrations

Quick start

• Quick start
  • @dotenv-run/cli
  • @dotenv-run/core
  • @dotenv-run/esbuild
  • @ngx-env/builder
  • Demos
  • Quick start
  • @dotenv-run/webpack
  • @dotenv-run/rollup
• Credits
• License

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.json

and 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

@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

@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

@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

@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 🔥
• ✅ Webpack and ESBuild support 🚀
• ✅ Runtime environment variables 🎉
• ✅ Loading priorities of environment variables with Monorepo Support (Nx, Turbo, etc.) ✨
• ✅ Easy to use, no configuration required
• ✅ Up to date with latest Angular versions
• ✅ Supports all Angular CLI commands (Karma is not supported on v19)
• ✅ Supports process.env and import.meta.env usage in TypeScript
• ✅ Filters sensitive variables using a Regular Expression
• ✅ Used by popular repositories
  • Official Microsoft Azure Samples
  • Official Quarkus Workshop
  • Scholarsome by Redhat
  • Dan Wahlin's Angular-JumpStart
• ✅ Active development and support

Testimonials

motdotla - dotenv author and maintainer @dotenvx

NB: Angular not Angular.js :P

manekinekko - SSE @microsoft

Demos

• v19 with vite/esbuild builder
• v16 with webpack builder

Quick start

ng add @ngx-env/builder

Environment 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

@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

@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: "../../.." })],
};

Credits

• dotenv

License

MIT © Chihab Otmani