runtime-env-cli

runtime-env-cli is an NPM package that helps manage environment variables in web applications. It allows environment-agnostic build for frameworks like create-react-app and inject environment variables as window.env in html files during server startup.

Usage

Development Mode

1. Install runtime-env-cli as development dependency.

   pnpm:

    pnpm i -D runtime-env-cli

   npm:

    npm i -D runtime-env-cli

   Yarn:

    pnpm add -D runtime-env-cli

2. Import runtime-env-cli in top-level javascript/typescript file for aliasing process.env as windows.env in development mode.

   import "runtime-env-cli";

   It also provides type-safety for windows.env.

   Note: You can make it further type-safe by extending interfaces ProcessEnv or WindowEnv.

   Use environment variables from window.env:

   window.env.SAMPLE_ENV;

Production Mode

1. Generate static files for your application.

   npm run build

2. Install runtime-env-cli in hosting environment (if using docker, do this in the last stage).

   npm i -g runtime-env-cli

3. Run the cli to inject env into html files before serving files (in docker, do this in entrypoint following by serving files, refer example).

   runtime-env [options]

   Note: CLI uses process.env to get environment while injecting. Any matching environment variables already configured in shell will be read. To use .env files, first load it before running this (refer dotenv-cli).

CLI Options

• -v, --version: output the version number.
• -p, --path [paths...] (optional): glob patterns to match path of html files (default: ["./build/*/.html"]).
• -m, --match <regex>: regular expression to match environment variable names to be injected.
• -h, --help: display help for command.

example

runtime-env --path "./**/*.html" --match "^APP_ENV_"

This will inject all environment variables prefixed with APP_ENV_ as window.env object into all html files under working directory.

Changelog

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.0.1 (2024-02-14)

Bug Fixes

• cd: npm deployment issue (644151c)

1.0.0 (2024-02-14)

Features

• inject env in html at runtime (b44bbd3)

Bug Fixes

• bin with commonjs build (7f9dd18)
• build: cleanup build artifacts (cafb0a6)
• build: include missing files in dist dir (5ad0bd4)

1.0.0-alpha.3 (2024-02-13)

Bug Fixes

• build: include missing files in dist dir (5ad0bd4)

1.0.0-alpha.2 (2024-02-13)

Bug Fixes

• build: cleanup build artifacts (cafb0a6)

1.0.0-alpha.1 (2024-01-18)

Features

• inject env in html at runtime (b44bbd3)

Bug Fixes

• bin with commonjs build (7f9dd18)