https://github.com/runtime-env/runtime-env
Build once, deploy anywhere. Framework agnostic environment variables generator and validator
https://github.com/runtime-env/runtime-env
12-factor-app docker json-schema runtime-config twelve-factor
Last synced: 2 days ago
JSON representation
Build once, deploy anywhere. Framework agnostic environment variables generator and validator
- Host: GitHub
- URL: https://github.com/runtime-env/runtime-env
- Owner: runtime-env
- License: mit
- Created: 2023-10-30T01:00:42.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-09T23:03:43.000Z (6 days ago)
- Last Synced: 2025-07-10T09:18:53.217Z (6 days ago)
- Topics: 12-factor-app, docker, json-schema, runtime-config, twelve-factor
- Language: TypeScript
- Homepage:
- Size: 5.83 MB
- Stars: 32
- Watchers: 0
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# runtime-env
> **The twelve-factor app stores config in _environment variables_** (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code. - [The Twelve-Factor App](https://12factor.net/config)
[](https://github.com/runtime-env/runtime-env/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@runtime-env/cli)
## Table of Content
- [Installation](#installation)
- [Get Started](#get-started)
- [Setup](#setup)
- [Commands](#commands)
- [Syntax](#syntax)
## Installation
```sh
npm install --save-dev @runtime-env/cli
```
## Get Started
1. Create a JSON-schema file and define your environment variables:
`.runtimeenvschema.json`
```json
{
"type": "object",
"properties": {
"TITLE": {
"type": "string"
}
},
"required": ["TITLE"]
}
```
2. Using environment variables in your code:
`index.js`
```js
document.body.innerHTML = globalThis.runtimeEnv.TITLE;
```
3. Set environment variables in your terminal:
```sh
export TITLE="Hello Runtime Env"
```
4. Use the `runtime-env` CLI to generate a JavaScript file:
```sh
npx --package @runtime-env/cli runtime-env gen-js --output-file runtime-env.js
```
5. Import the generated file before importing the entry point:
`index.html`
```html
```
6. Open `index.html` in your browser, and you will see `Hello Runtime Env` in the console.
7. Set a new environment variable, regenerate the JavaScript file, and refresh the page:
```sh
export TITLE="Yo Runtime Env"
npx --package @runtime-env/cli runtime-env gen-js --output-file runtime-env.js
```
8. That's it! You don't need to rebuild your app to update the environment variables anymore.
## Setup
1. Create a JSON-schema file:
`.runtimeenvschema.json`:
```json
{
"type": "object",
"properties": {
"TAG_ID": {
"type": "string"
},
"FIREBASE_CONFIG": {
"type": "object",
"properties": {
"apiKey": {
"type": "string"
},
"authDomain": {
"type": "string"
}
},
"required": ["apiKey", "authDomain"]
}
},
"required": ["TAG_ID", "FIREBASE_CONFIG"]
}
```
You could use other file name by running `npx -p @runtime-env/cli runtime-env --schema-file ...`.
Runtime-env uses Ajv to parse your JSON-schema.
1. Configure your package.json, Dockerfile, etc. to generate, and interpolate files:
- To generate a JavaScript file which contains the environment variables, you will execute `runtime-env gen-js`:
```sh
$ npx -p @runtime-env/cli runtime-env gen-js --output-file runtime-env.js
```
```js
// runtime-env.js
globalThis.runtimeEnv = {
TAG_ID: "G-ABCD12345",
FIREBASE_CONFIG: {
apiKey: "AIzaSk2CngkeAyDJr2BhzSprQXp8PsZs3VFJFMA",
authDomain: "example.firebaseapp.com",
},
};
```
And make sure to import the generated file before importing the entry point:
```html
```
- If you are using TypeScript, you can also generate a _declaration file_ by running `runtime-env gen-ts`:
```sh
$ npx -p @runtime-env/cli runtime-env gen-ts --output-file runtime-env.d.ts
```
```ts
// runtime-env.d.ts
// type DeepReadonly = ...
declare global {
var runtimeEnv: RuntimeEnv;
}
export type RuntimeEnv = DeepReadonly<{
TAG_ID: string;
FIREBASE_CONFIG: {
apiKey: string;
authDomain: string;
};
}>;
```
- For `index.html` and other non-JavaScript files, if needed, you can run `runtime-env interpolate`:
```sh
$ npx -p @runtime-env/cli runtime-env interpolate --input-file index.html --output-file index.html
```
```html
```
1. Further setups:
- You **NEED** to set up your web server to stop runtime-env.js to be cached by browser or CDNs.
- To use runtime-env on systems that don't have Node.js installed, you'll need to pack `runtime-env` CLI into a single runnable file. Here's how you can do it:
- Make a single runnable app using NodeJS's [Single Executable Applications](https://nodejs.org/api/single-executable-applications.html) feature (experimental).
- Pack runtime-env into a runnable file using [pkg](https://github.com/vercel/pkg):
```sh
$ pkg ./node_modules/@runtime-env/cli/bin/runtime-env.js --target node18-alpine-x64 --output runtime-env
```
- If you're making a PWA (Progressive Web App), you **HAVE TO** set up your ServiceWorker to choose the right way to cache runtime-env.js.
## Commands
- `$ npx -p @runtime-env/cli runtime-env --help`
```
Usage: runtime-env [options] [command]
Options:
-V, --version output the version number
--global-variable-name specify the global variable name (default: "runtimeEnv")
--schema-file specify the json schema file to be loaded (default: ".runtimeenvschema.json")
--watch turn on watch mode (default: false)
-h, --help display help for command
Commands:
gen-js [options] generate a JavaScript file that includes environment variables within an object, making them
accessible through the globalThis property
gen-ts [options] generate a TypeScript file that provides the corresponding type definitions for the JavaScript
file generated by the gen-js command
interpolate [options] perform template interpolation by substituting environment variables
help [command] display help for command
```
- `$ npx -p @runtime-env/cli runtime-env gen-js --help`
```
Usage: runtime-env gen-js [options]
generate a JavaScript file that includes environment variables within an object, making them accessible through the globalThis property
Options:
--env-file set environment variables from supplied file (requires Node.js v20.12.0) (default: [])
--output-file specify the output file to be written instead of being piped to stdout
-h, --help display help for command
```
- `$ npx -p @runtime-env/cli runtime-env gen-ts --help`
```
Usage: runtime-env gen-ts [options]
generate a TypeScript file that provides the corresponding type definitions for the JavaScript file generated by the gen-js command
Options:
--output-file specify the output file to be written instead of being piped to stdout
-h, --help display help for command
```
- `$ npx -p @runtime-env/cli runtime-env interpolate --help`
```
Usage: runtime-env interpolate [options]
perform template interpolation by substituting environment variables
Options:
--env-file set environment variables from supplied file (requires Node.js v20.12.0) (default: [])
--input-file specify the input file to be loaded instead of being read from stdin
--output-file specify the output file to be written instead of being piped to stdout
-h, --help display help for command
```
## Syntax
- For JavaScript, you can read environment variables through the `globalThis` property:
```js
// Syntax: .
initializeApp(runtimeEnv.FIREBASE_CONFIG);
```
- For interpolation, you can use environment variables by a template:
```html
```