JoseVSeb / runtime-env

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:

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