{"id":16375836,"url":"https://github.com/micha149/vite-plugin-runtime-env","last_synced_at":"2025-03-23T03:32:45.548Z","repository":{"id":114555532,"uuid":"609455395","full_name":"micha149/vite-plugin-runtime-env","owner":"micha149","description":"Vite plugin which enables you to configure your environment variables when deploying your app.","archived":false,"fork":false,"pushed_at":"2023-03-06T13:47:14.000Z","size":12,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-08-14T10:26:03.319Z","etag":null,"topics":["12-factor","docker","dot-env","environment","vite","vite-plugin"],"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/micha149.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2023-03-04T08:13:43.000Z","updated_at":"2024-07-24T10:23:15.000Z","dependencies_parsed_at":"2023-05-29T19:30:30.230Z","dependency_job_id":null,"html_url":"https://github.com/micha149/vite-plugin-runtime-env","commit_stats":{"total_commits":8,"total_committers":2,"mean_commits":4.0,"dds":0.125,"last_synced_commit":"a25e7a5cf6a899347262f4d892421013b8c1c92d"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micha149%2Fvite-plugin-runtime-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micha149%2Fvite-plugin-runtime-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micha149%2Fvite-plugin-runtime-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micha149%2Fvite-plugin-runtime-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micha149","download_url":"https://codeload.github.com/micha149/vite-plugin-runtime-env/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244267406,"owners_count":20425836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","docker","dot-env","environment","vite","vite-plugin"],"created_at":"2024-10-11T03:22:21.646Z","updated_at":"2025-03-23T03:32:45.059Z","avatar_url":"https://github.com/micha149.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vite-plugin-runtime-env\n\n[![Test Status](https://img.shields.io/github/actions/workflow/status/micha149/vite-plugin-runtime-env/test.yaml?branch=master\u0026style=flat-square)](https://github.com/micha149/vite-plugin-runtime-env/actions?query=workflow%3ATest)\n[![npm](https://img.shields.io/npm/v/vite-plugin-runtime-env?style=flat-square)](https://www.npmjs.com/package/vite-plugin-runtime-env)\n[![License](https://img.shields.io/github/license/micha149/vite-plugin-runtime-env?style=flat-square)](LICENSE)\n\nInject environment variables on runtime rather than build time.\n\n## Installation\n\n```bash\nnpm install --save-dev vite-plugin-runtime-env\n```\n\n## Usage\n\nFirst you need to add the plugin to your vite config.\n\n```typescript\nimport runtimeEnv from 'vite-plugin-runtime-env';\n\nexport default defineConfig({\n  plugins: [\n    runtimeEnv(),\n  ]\n});\n```\n\nWhen building your app, the plugin replaces all occurences of `import.meta.env.VITE_MY_VARIABLE` with somethink like `window.env.VITE_MY_VARIABLE` and inserts a mapping into `index.html`.\nThe mapping contains placeholder variables like `${VITE_MY_VARIABLE}` which can be substituted using [`envsubst`][envsubst] or [`npx envsub`][envsub] when deploying your app.\n\n```sh\ncp dist/index.html index.html.template\nenvsubst \u003c index.html.template \u003e dist/index.html\n```\n\nOr, when Node.js is available in your deployment environment:\n\n```sh\nnpx envsub dist/index.html\n```\n\nBoth examples assume that your variables are defined in the deploy environment. The node tool also supports `.env` files\nas arguments.\n\n## Configuration\n\n### `variableName`\nThe variable name to be used for replacements. Defaults to `'window.env'`.\n\nExample:\n```typescript\nimport runtimeEnv from 'vite-plugin-runtime-env';\n\nexport default defineConfig({\n  plugins: [\n    runtimeEnv({\n        varialbeName: 'window.myCustomEnv',\n    }),\n  ]\n});\n```\n\n### `injectHtml`\nWheter to inject the variables map into `index.html`.\nSometimes it can be handy to not have the map in index.html and load an external javascript file which sets the object.\nDefaults to `true`.\n\nExample:\n```typescript\nimport runtimeEnv from 'vite-plugin-runtime-env';\n\nexport default defineConfig({\n  plugins: [\n    runtimeEnv({\n        injectHtml: false,\n    }),\n  ]\n});\n```\n\n### `substitutionSyntax`\nThe syntax for inserted placeholders.\nThis should match the tool you are using to substitute the variables on deployment.\nValid values are `'dollar-basic'` for `$MYVAR`, `'dollar-curly'` for `${MYVAR}` and `'handlebars'` for `{{MYVAR}}`.\nDefaults to `'dollar-curly'`.\n\nExample:\n```typescript\nimport runtimeEnv from 'vite-plugin-runtime-env';\n\nexport default defineConfig({\n  plugins: [\n    runtimeEnv({\n        substitutionSyntax: 'handlebars',\n    }),\n  ]\n});\n```\n\nNow you can use a custom script using handlebars to inject the variables.\n\n### `ignoreEnv`\nVariable names to be ignored by this plugin.\nThey will remain in the code and will be statically replaced by Vite on build time.\nThis can be useful for informations which are known on build time and not be configurable on runtime, like the version number of the current build.\nValid values are an array of strings, containing each variable to be ignored, or a function which gets each variable as an input and return `true` if this variable should be skipped.\n\nExample:\n```typescript\nimport runtimeEnv from 'vite-plugin-runtime-env';\n\nexport default defineConfig({\n  plugins: [\n    runtimeEnv({\n        ignoreEnv: ['VITE_CURRENT_VERSION'],\n    }),\n  ]\n});\n```\n\nExample using a function:\n```typescript\nimport runtimeEnv from 'vite-plugin-runtime-env';\n\nexport default defineConfig({\n  plugins: [\n    runtimeEnv({\n        ignoreEnv: env =\u003e env.startsWith('VITE_STATIC_'),\n    }),\n  ]\n});\n```\n\n## Motivation\n\nIf your project want to adhere to the [12 factor principles][12factor] it can be cumbersome that Vite replaces your environment variables with static content on build time.\nFollowing the principle „I – Config” we want to store configurations in the environment.\nAnd funnily enough, this is also implied by the name „environment variable”.\nRespecting these principles can be useful when running your app in a containerized setup like Docker or Kubernetes.\n\nA workaround would be to run `vite build` when deploying the app.\nBut this may slow down our deployments, especially when deploying multiple instances and each one builds the app for its own.\nAlso, this would be contrary to principle „V – Build, release, run” which requires strict separation between the build, release, and run stages.\n\nTo be able to create a single bundle and run the same bundle in different environments like testing, staging and\nproduction, we need to be able to pass some configurations when the app is deployed.\nAfter a lot of projects where each solves this same problem with its own custom workaround, I created this plugin to rule them all.\n\n[envsubst]: https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html\n[envsub]: https://www.npmjs.com/package/envsub\n[12factor]: https://12factor.net/","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicha149%2Fvite-plugin-runtime-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicha149%2Fvite-plugin-runtime-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicha149%2Fvite-plugin-runtime-env/lists"}