@xcapit/runtime-env-manager

Keep browser runtime environment declarations in sync with a single command. Add or remove a variable across your startup script, env.js template, local browser defaults, TypeScript interface, test setup, example environment file, and README.

Designed for frontend projects that generate env.js at startup with envsubst and expose configuration through window.__env.

Runtime values are visible to anyone using your application. Use public configuration values only; never add secrets or credentials.

Requirements

• Node.js 20 or later.
• An existing project with the file structure and declaration formats described below.
• envsubst available in the environment that generates your runtime env.js. The CLI itself does not run envsubst.

Installation

npm install --save-dev @xcapit/runtime-env-manager

Add these scripts to your project's package.json:

{
  "scripts": {
    "env:add": "xcapit-runtime-env add",
    "env:remove": "xcapit-runtime-env remove"
  }
}

Configuration

Create .runtime-env.config.json in your project root and run commands from that directory:

{
  "files": {
    "entrypoint": "entrypoint.sh",
    "template": ".nginx/env.js.template",
    "example": "variables.env.example",
    "browser": "public/env.js",
    "types": "src/environments/environment.ts",
    "tests": "src/test-setup.ts",
    "readme": "README.md"
  },
  "readmeTableHeader": "| Variable | Purpose |"
}

All seven file entries and readmeTableHeader are required. Paths are resolved from the current working directory and must remain inside the project directory. The files must already exist; the CLI updates declarations rather than scaffolding a project.

| Configuration key | Updated declarations | | --- | --- | | entrypoint | The VARIABLES list and the explicit substitution list passed to envsubst | | template | Runtime placeholders in the browser JavaScript template | | example | Example values in NAME=value format | | browser | Local browser defaults in window.__env | | types | Properties in the RuntimeEnv TypeScript interface | | tests | Browser environment values used by tests | | readme | Rows in the runtime environment variables table |

Expected file formats

The CLI uses text matching, so existing declarations must follow these formats.

The startup script must contain a single-quoted VARIABLES assignment and a single-quoted envsubst substitution list followed by a line continuation:

VARIABLES='API_URL'

envsubst '${API_URL}' \
  < /etc/nginx/env.js.template \
  > /usr/share/nginx/html/env.js

The template uses runtime placeholders inside a JavaScript object:

window.__env = Object.freeze({
  apiUrl: "${API_URL}",
});

The browser defaults and test setup use the same object layout with literal values:

window.__env = {
  apiUrl: "https://api.example.com",
};

Object properties must occupy one line each with two leading spaces. The closing }); or }; must be on its own line.

The TypeScript interface must be followed by a blank line and declare global:

export interface RuntimeEnv {
  apiUrl: string;
}

declare global {
  interface Window {
    __env: RuntimeEnv;
  }
}

The example environment file uses one variable per line:

API_URL=https://api.example.com

The README must contain a Markdown table whose header matches readmeTableHeader exactly. Variable names in its rows must be wrapped in backticks:

| Variable | Purpose |
| --- | --- |
| `API_URL` | API base URL |

Commands

Add a variable

npm run env:add -- API_TIMEOUT 30 "API timeout in seconds"

This adds API_TIMEOUT to the startup script, template, example environment file, and README. It also adds the camelCase property apiTimeout to the browser defaults, TypeScript interface, and test setup.

For a boolean variable:

npm run env:add -- FEATURE_ENABLED true "Enables the feature"

Remove a variable

npm run env:remove -- API_TIMEOUT

This removes the variable from all seven configured files. Pass only the variable name.

You can also invoke the installed CLI directly:

npx xcapit-runtime-env add API_TIMEOUT 30 "API timeout in seconds"
npx xcapit-runtime-env remove API_TIMEOUT

Naming and values

• Variable names must start with an uppercase letter and contain only uppercase letters, digits, and underscores.
• Uppercase underscore names become camelCase properties: API_TIMEOUT becomes apiTimeout.
• The exact values true and false become booleans. All other values, including numbers such as 30, become strings.
• Adding a variable requires a non-empty example value and a description. Quote arguments containing spaces.
• Example values cannot contain double quotes, backslashes, or control characters. Descriptions cannot contain vertical bars or line breaks.
• Test values are generated automatically: false for booleans and test_<lowercase_variable_name> for strings.

Use example values that are valid for your environment file and runtime template. Update actual deployment values separately. With the configuration above, the CLI leaves your local variables.env untouched.

Commands exit with a nonzero status when validation fails, a variable already exists when adding, or a required declaration is missing when removing. Review the generated changes before committing them.