vite-plugin-runtime-config

A vite plugin for runtime configuration.

This is a plugin to vite which enables configuring a project at runtime instead of at build-time. It is conceptually the middle ground between rebuilding an application everytime a configuration changes and server-side-rendering.

Background

At Viva con Agua we frequently encountered the problem of configuring an application that is bundled together using vite build and then served as static files by a sophisticated webserver. Traditionally vite supports dynamic configuration through env variables however those are read when the app is built and statically baked into it. We however wanted a similar mechanism that does not require server-side-rendering but still enables us change certain aspects our apps dynamically.

Also, we conceptually did not think that changing configuration should require recompiling an app.

Install

The package is published on npm, and you can install it by running

npm install --save-dev vite-plugin-runtime-config

Usage

To get started, simply add the plugin to your vite.config.ts. The runtimeConfig() function also accepts an optional argument object that is defined and documented in options.ts.

import { defineConfig } from "vite";
import runtimeConfig from "vite-plugin-runtime-config";

export default defineConfig({
    plugins: [runtimeConfig()],
});

You now have the ability to reference dynamic configuration values inside your index.html file. You can either reference individual configuration values or a complete json representation of the configuration.

| Syntax | Usage | Example | | ---------------------- | ------------------------------------------ | ---------------------------------------------------- | | {{ VITE_X }} | Reference to the configuration VITE_X | <meta name="test" content="{{ VITE_META_TAG }}" /> | | {% VITE_RT_CONFIG %} | Complete json representation of the config | <p>Config is {% VITE_RT_CONFIG %}</p> |

Additionally, the plugin automatically injects a script to your document that populates window.config with the complete runtime configuration. You can use this object throughout all your code without any restrictions.

During Development

During development, all references to runtime configuration in index.html are automatically replaced from vite's env variables. There is no additional work required to make this work.

In Production

Since this plugin is aimed at a deployment mode in which a static bundle is served by an external webserver vite is normally not involved at all. To get around this, scripts or programs can be emitted in addition to the normal app bundled which perform the configuration replacement. By default, only a JS script is emitted. See available plugin options for possible output modi.

Building and configuring your app now boils down to the following steps:

1. At build-time

   npx vite build

   Assuming a minimal default configuration, the following dist/ folder could be generated. At this point index.html still contains un-replaced configuration references and needs to be processed before serving it to users.

   dist
   ├── assets
   │   └── index.0812df02.js
   ├── index.html
   └── patch_runtime_config.js

2. At runtime

   node dist/patch_runtime_config.js --in dist/index.html --out dist/index.html

   The script will automatically replace configuration references from environment variables as well as .env files. It should behave exactly the same as vite itself does during development.

   The script accepts additional arguments which are defined in script_entrypoint.ts and can also be discovered by calling it wich --help.

Testing

If you have code that relies on runtime configuration, you need to populate the window.config object before executing tests. For vitest, a helper hook is implemented to set and unset window.config before and after tests. See its usage in test_project/main.test.ts.

Example Project

This repository contains the test_project which is a minimal VueJS application that uses vite-plugin-runtime-config. You can look in there for inspiration.

Api

The most relevant API for users are plugin options, testing utilities and replacer program arguments.

Additionally, the whole project is authored in typescript and type declaration files are distributed as part of our releases. Your IDE should pick this up pretty well and offer you good autocompletion and documentation.

Contributing

See CONTRIBUTING.md for more details.