Make your application easily configurable.

A simple way to provide runtime configuration for your React application, with localStorage overrides and hot-reload support ⚡️!

Why

Most web applications usually need to support and function within a variety of distinct environments: local, development, staging, production, on-prem, etc. This project aims to provide flexibility to React applications by making certain properties configurable at runtime, allowing the app to be customized based on a pre-determined configmap respective to the environment. This is especially powerful when combined with Kubernetes configmaps.

Here are examples of some real-world values that can be helpful when configurable at runtime:

- Primary Color
- Backend API URL
- Feature Flags
- …

How

The configuration can be set by _either_:

- setting a configuration property on window with reasonable defaults. Consider,

``js
window.MY_APP_CONFIG = {
primaryColor: "green",
};
`

- _or_ by setting a value in localStorage. Consider,

`js
localStorage.setItem("MY_APP_CONFIG.primaryColor", "green");
`

The localStorage option could provide a nice delineation between environments: you _could_ set your local environment to green, and staging to red for example, in order to never be confused about what you're looking at when developing locally and testing against a deployed development environment: if it's green, it's local.

This configuration is then easily read by the simple React hook that this library exports.

Getting started

1. npm i react-runtime-config
1. Create a namespace for your config:

`tsx
// components/Config.tsx
import createConfig from "react-runtime-config";

/**
* useConfig and useAdminConfig are now React hooks that you can use in your app.
*
* useConfig provides config getter & setter, useAdminConfig provides data in order
* to visualize your config map with ease. More on this further down.
*/
export const { useConfig, useAdminConfig } = createConfig({
namespace: "MY_APP_CONFIG",
schema: {
color: {
type: "string",
enum: ["blue" as const, "green" as const, "pink" as const], // as const is required to have nice autocompletion
description: "Main color of the application",
},
backend: {
type: "string",
description: "Backend url", // config without default need to be provided into window.MY_APP_CONFIG
},
port: {
type: "number", // This schema can be retrieved after in useAdminConfig().fields
description: "Backend port",
min: 1,
max: 65535,
default: 8000, // config with default don't have to be set on window.MY_APP_CONFIG
},
monitoringLink: {
type: "custom",
description: "Link of the monitoring",
parser: value => {
if (typeof value === "object" && typeof value.url === "string" && typeof value.displayName === "string") {
// The type will be inferred from the return type
return { url: value.url as string, displayName: value.displayName as string };
}
// This error will be shown if the window.MY_APP_CONFIG.monitoringLink can't be parsed or if we setConfig an invalid value
throw new Error("Monitoring link invalid!");
},
},
isLive: {
type: "boolean",
default: false,
},
},
});
`

You can now use the created hooks everywhere in your application. Thoses hooks are totally typesafe, connected to your configuration. This means that you can easily track down all your configuration usage across your entire application and have autocompletion on the keys.

$3

`tsx
// components/MyComponents.tsx
import react from "React";
import { useConfig } from "./Config";

const MyComponent = () => {
const { getConfig } = useConfig();

return

My title

- localStorage.getItem("MY_APP_CONFIG.color")
- window.MY_APP_CONFIG.color
- schema.color.default

Namespaced useConfig hook

In a large application, you may have multiple instances of useConfig from different createConfig. So far every useConfig will return a set of getConfig, setConfig and getAllConfig.

To avoid any confusion or having to manually rename every usage of useConfig in a large application, you can use the configNamespace options.

`ts
// themeConfig.ts
export const { useConfig: useThemeConfig } = createConfig({
namespace: "theme",
schema: {},
configNamespace: "theme", // <- here
});

// apiConfig.ts
export const { useConfig: useApiConfig } = createConfig({
namespace: "api",
schema: {},
configNamespace: "api", // <- here
});

// App.ts
import { useThemeConfig } from "./themeConfig";
import { useApiConfig } from "./apiConfig";

export const App = () => {
// All methods are now namespaces
// no more name conflicts :)
const { getThemeConfig } = useThemeConfig();
const { getApiConfig } = useApiConfig();

return