{"id":16077779,"url":"https://github.com/runtime-env/runtime-env","last_synced_at":"2026-02-07T05:04:08.985Z","repository":{"id":205424650,"uuid":"711682129","full_name":"runtime-env/runtime-env","owner":"runtime-env","description":"Build once, deploy anywhere. Framework agnostic environment variables generator and validator","archived":false,"fork":false,"pushed_at":"2026-01-31T02:17:50.000Z","size":8573,"stargazers_count":41,"open_issues_count":8,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-31T17:57:44.191Z","etag":null,"topics":["12-factor-app","csp","docker","json-schema","runtime-config","twelve-factor","vite"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/runtime-env.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"buy_me_a_coffee":"iendeavor"}},"created_at":"2023-10-30T01:00:42.000Z","updated_at":"2026-01-31T02:17:29.000Z","dependencies_parsed_at":"2026-01-28T17:10:20.942Z","dependency_job_id":null,"html_url":"https://github.com/runtime-env/runtime-env","commit_stats":null,"previous_names":["runtime-env/runtime-env"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/runtime-env/runtime-env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtime-env%2Fruntime-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtime-env%2Fruntime-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtime-env%2Fruntime-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtime-env%2Fruntime-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runtime-env","download_url":"https://codeload.github.com/runtime-env/runtime-env/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtime-env%2Fruntime-env/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29186743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T03:35:06.566Z","status":"ssl_error","status_checked_at":"2026-02-07T03:34:57.604Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["12-factor-app","csp","docker","json-schema","runtime-config","twelve-factor","vite"],"created_at":"2024-10-09T10:03:13.218Z","updated_at":"2026-02-07T05:04:08.971Z","avatar_url":"https://github.com/runtime-env.png","language":"TypeScript","funding_links":["https://buymeacoffee.com/iendeavor"],"categories":["docker"],"sub_categories":[],"readme":"# runtime-env\n\n\u003e **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)\n\n[![CI](https://github.com/runtime-env/runtime-env/actions/workflows/ci.yml/badge.svg)](https://github.com/runtime-env/runtime-env/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@runtime-env/cli?color=blue)](https://www.npmjs.com/package/@runtime-env/cli)\n[![npm](https://img.shields.io/npm/v/@runtime-env/vite-plugin?color=blue)](https://www.npmjs.com/package/@runtime-env/vite-plugin)\n\n\u003e [!TIP]\n\u003e Using Vite? Check out our [zero-config Vite plugin](./packages/vite-plugin/README.md) for a seamless integration.\n\n## Table of Content\n\n- [Installation](#installation)\n- [Get Started](#get-started)\n- [Setup](#setup)\n- [Commands](#commands)\n- [Syntax](#syntax)\n\n## Installation\n\n```sh\nnpm install --save-dev @runtime-env/cli\n```\n\n## Get Started\n\n1. Create a JSON-schema file and define your environment variables:\n\n   `.runtimeenvschema.json`\n\n   ```json\n   {\n     \"type\": \"object\",\n     \"properties\": {\n       \"TITLE\": {\n         \"type\": \"string\"\n       }\n     },\n     \"required\": [\"TITLE\"]\n   }\n   ```\n\n2. Using environment variables in your code:\n\n   `index.js`\n\n   ```js\n   document.body.textContent = globalThis.runtimeEnv.TITLE;\n   ```\n\n3. Set environment variables in your terminal:\n\n   ```sh\n   export TITLE=\"Hello Runtime Env\"\n   ```\n\n4. Use the `runtime-env` CLI to generate a JavaScript file:\n\n   ```sh\n   npx --package @runtime-env/cli runtime-env gen-js --output-file runtime-env.js\n   ```\n\n5. Import the generated file before importing the entry point:\n\n   `index.html`\n\n   ```html\n   \u003c!doctype html\u003e\n   \u003chtml\u003e\n     \u003cbody\u003e\n       \u003cscript src=\"./runtime-env.js\"\u003e\u003c/script\u003e\n       \u003cscript src=\"./index.js\"\u003e\u003c/script\u003e\n     \u003c/body\u003e\n   \u003c/html\u003e\n   ```\n\n6. Open `index.html` in your browser, and you will see `Hello Runtime Env` in the console.\n\n7. Set a new environment variable, regenerate the JavaScript file, and refresh the page:\n\n   ```sh\n   export TITLE=\"Yo Runtime Env\"\n   npx --package @runtime-env/cli runtime-env gen-js --output-file runtime-env.js\n   ```\n\n8. That's it! You don't need to rebuild your app to update the environment variables anymore.\n\n## Setup\n\n1. Create a \u003ca href='https://json-schema.org/' target='_blank'\u003eJSON-schema\u003c/a\u003e file:\n\n   `.runtimeenvschema.json`:\n\n   ```json\n   {\n     \"type\": \"object\",\n     \"properties\": {\n       \"TAG_ID\": {\n         \"type\": \"string\"\n       },\n       \"FIREBASE_CONFIG\": {\n         \"type\": \"object\",\n         \"properties\": {\n           \"apiKey\": {\n             \"type\": \"string\"\n           },\n           \"authDomain\": {\n             \"type\": \"string\"\n           }\n         },\n         \"required\": [\"apiKey\", \"authDomain\"]\n       }\n     },\n     \"required\": [\"TAG_ID\", \"FIREBASE_CONFIG\"]\n   }\n   ```\n\n   You could use other file name by running `npx -p @runtime-env/cli runtime-env --schema-file ...`.\n\n   Runtime-env uses \u003ca href='https://ajv.js.org/' target='_blank'\u003eAjv\u003c/a\u003e to parse your JSON-schema.\n\n1. Configure your package.json, Dockerfile, etc. to generate, and interpolate files:\n   - To generate a JavaScript file which contains the environment variables, you will execute `runtime-env gen-js`:\n\n     ```sh\n     $ npx -p @runtime-env/cli runtime-env gen-js --output-file runtime-env.js\n     ```\n\n     ```js\n     // runtime-env.js\n     globalThis.runtimeEnv = {\n       TAG_ID: \"G-ABCD12345\",\n       FIREBASE_CONFIG: {\n         apiKey: \"AIzaSk2CngkeAyDJr2BhzSprQXp8PsZs3VFJFMA\",\n         authDomain: \"example.firebaseapp.com\",\n       },\n     };\n     ```\n\n     And make sure to import the generated file before importing the entry point:\n\n     ```html\n     \u003c!-- index.html --\u003e\n     \u003cscript src=\"/runtime-env.js\"\u003e\u003c/script\u003e\n     \u003cscript src=\"/index.js\"\u003e\u003c/script\u003e\n     ```\n\n   - If you are using TypeScript, you can also generate a _declaration file_ by running `runtime-env gen-ts`:\n\n     ```sh\n     $ npx -p @runtime-env/cli runtime-env gen-ts --output-file runtime-env.d.ts\n     ```\n\n     ```ts\n     // runtime-env.d.ts\n     // type DeepReadonly\u003cT\u003e = ...\n\n     declare global {\n       var runtimeEnv: RuntimeEnv;\n     }\n\n     export type RuntimeEnv = DeepReadonly\u003c{\n       TAG_ID: string;\n       FIREBASE_CONFIG: {\n         apiKey: string;\n         authDomain: string;\n       };\n     }\u003e;\n     ```\n\n   - For `index.html` and other non-JavaScript files, if needed, you can run `runtime-env interpolate`:\n\n     ```sh\n     $ npx -p @runtime-env/cli runtime-env interpolate --input-file index.html --output-file index.html\n     ```\n\n     ```html\n     \u003cscript\n       async\n       src=\"https://www.googletagmanager.com/gtag/js?id=G-ABCD12345\"\n     \u003e\u003c/script\u003e\n     ```\n\n1. Further setups:\n   - You **NEED** to set up your web server to stop runtime-env.js to be cached by browser or CDNs.\n\n   - 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. You can make a single runnable app using NodeJS's [Single Executable Applications](https://nodejs.org/api/single-executable-applications.html) feature.\n\n   - 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.\n\n## Commands\n\n- `$ npx -p @runtime-env/cli runtime-env --help`\n\n  ```\n  Usage: runtime-env [options] [command]\n\n  Options:\n    -V, --version                                output the version number\n    --global-variable-name \u003cglobalVariableName\u003e  specify the global variable name (default: \"runtimeEnv\")\n    --schema-file \u003cschemaFile\u003e                   specify the json schema file to be loaded (default: \".runtimeenvschema.json\")\n    --watch                                      turn on watch mode (default: false)\n    -h, --help                                   display help for command\n\n  Commands:\n    gen-js [options]                             generate a JavaScript file that includes environment variables within an object, making them\n                                                accessible through the globalThis property\n    gen-ts [options]                             generate a TypeScript file that provides the corresponding type definitions for the JavaScript\n                                                file generated by the gen-js command\n    interpolate [options]                        perform template interpolation by substituting environment variables\n    help [command]                               display help for command\n  ```\n\n- `$ npx -p @runtime-env/cli runtime-env gen-js --help`\n\n  ```\n  Usage: runtime-env gen-js [options]\n\n  generate a JavaScript file that includes environment variables within an object, making them accessible through the globalThis property\n\n  Options:\n    --env-file \u003cenvFile...\u003e     set environment variables from supplied file (requires Node.js v20.12.0) (default: [])\n    --output-file \u003coutputFile\u003e  specify the output file to be written instead of being piped to stdout\n    -h, --help                  display help for command\n  ```\n\n- `$ npx -p @runtime-env/cli runtime-env gen-ts --help`\n\n  ```\n  Usage: runtime-env gen-ts [options]\n\n  generate a TypeScript file that provides the corresponding type definitions for the JavaScript file generated by the gen-js command\n\n  Options:\n    --output-file \u003coutputFile\u003e  specify the output file to be written instead of being piped to stdout\n    -h, --help                  display help for command\n  ```\n\n- `$ npx -p @runtime-env/cli runtime-env interpolate --help`\n\n  ```\n  Usage: runtime-env interpolate [options]\n\n  perform template interpolation by substituting environment variables\n\n  Options:\n    --env-file \u003cenvFile...\u003e     set environment variables from supplied file (requires Node.js v20.12.0) (default: [])\n    --input-file \u003cinputFile\u003e    specify the input file to be loaded instead of being read from stdin\n    --output-file \u003coutputFile\u003e  specify the output file to be written instead of being piped to stdout\n    -h, --help                  display help for command\n  ```\n\n## Syntax\n\n- For JavaScript, you can read environment variables through the `globalThis` property:\n\n  ```js\n  // Syntax: \u003cglobalVariableName\u003e.\u003cenvironmentVariableName\u003e\n  initializeApp(runtimeEnv.FIREBASE_CONFIG);\n  ```\n\n- For interpolation, you can use environment variables by a \u003ca href='https://lodash.com/docs/4.17.15#template' target='_blank'\u003etemplate\u003c/a\u003e:\n\n  ```html\n  \u003c!-- Syntax: \u003c%= \u003cglobalVariableName\u003e.\u003cenvironmentVariableName\u003e %\u003e --\u003e\n  \u003cscript\n    async\n    src=\"https://www.googletagmanager.com/gtag/js?id=\u003c%= runtimeEnv.TAG_ID %\u003e\"\n  \u003e\u003c/script\u003e\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntime-env%2Fruntime-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruntime-env%2Fruntime-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntime-env%2Fruntime-env/lists"}