Skip to content

Seamlessly load environment variables. Supports cli, esbuild, rollup, vite, webpack, angular. ESM and Monorepos.

Notifications You must be signed in to change notification settings

chihab/dotenv-run

Folders and files

NameName
Last commit message
Last commit date

Latest commit

a9174bb Β· Dec 15, 2024
Nov 21, 2024
Nov 21, 2024
Mar 2, 2024
Nov 21, 2024
Dec 15, 2024
Dec 15, 2024
Nov 21, 2024
Mar 31, 2024
Nov 21, 2024
Jan 7, 2024
Nov 21, 2024
Dec 15, 2024
Dec 15, 2024
Dec 15, 2024
Nov 21, 2024
Jan 7, 2024

Repository files navigation

dotenv-run

monthly downloads

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

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 βœ…

Quick start

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
  • βœ… Supports process.env and import.meta.env usage in TypeScript
  • βœ… Filters sensitive variables using a Regular Expression
  • βœ… Used by popular repositories
  • βœ… Active development and support

Testimonials

motdotla - dotenv author and maintainer @dotenvx Description

NB: Angular not Angular.js :P

manekinekko - SSE @microsoft Description

Demos

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

License

MIT Β© Chihab Otmani