|
1 | | -# config-runtime |
| 1 | +# config-runtime |
| 2 | + |
| 3 | +## Motivation |
| 4 | + |
| 5 | +The handoff from the server to client of config values is not simple. Typings are hard, global variables are used and usually not cleaned up and there's no distinction of server and client only configs. |
| 6 | + |
| 7 | +This library is heavily inspired from [NextJS Runtime Config](https://nextjs.org/docs/api-reference/next.config.js/runtime-configuration). |
| 8 | + |
| 9 | +## Usage |
| 10 | + |
| 11 | +```ts |
| 12 | +import { CreateRuntimeConfig, RuntimeConfig } from 'config-runtime' |
| 13 | + |
| 14 | +interface ClientConfig { |
| 15 | + foo: string |
| 16 | +} |
| 17 | + |
| 18 | +interface ServerConfig { |
| 19 | + bar: number |
| 20 | +} |
| 21 | + |
| 22 | +const myConfig: RuntimeConfig<ClientConfig, ServerConfig> = { |
| 23 | + client: { |
| 24 | + foo: 'hello', |
| 25 | + }, |
| 26 | + server: { |
| 27 | + bar: 5, |
| 28 | + }, |
| 29 | +} |
| 30 | + |
| 31 | +const Config = new CreateRuntimeConfig<ClientConfig, ServerConfig>( |
| 32 | + // Useful for different kinds of config |
| 33 | + '__MY_CONFIG_NAME_TOTALLY_OPTIONAL__' |
| 34 | +) |
| 35 | + |
| 36 | +// Server entrypoint (only once) |
| 37 | +Config.setConfig( |
| 38 | + myConfig |
| 39 | +) |
| 40 | + |
| 41 | +// Handoff between server and client (html payload) |
| 42 | +`<script>${Config.serializedClientConfig}</script>` |
| 43 | + |
| 44 | +// On the server |
| 45 | +config.client // { foo: 'hello' } |
| 46 | +config.server // { bar: 5 } |
| 47 | + |
| 48 | +// On the client |
| 49 | +config.client // { foo: 'hello' } |
| 50 | +config.server // Error |
| 51 | +``` |
| 52 | + |
| 53 | +## Features |
| 54 | + |
| 55 | +1. Allows for server only config |
| 56 | +2. An app could have as many configs as it wants (They are cached by the configName parameter in `new CreateRuntimeConfig(configName)`) |
| 57 | +3. Caching enabled (Saves to an in memory variable, never to the global scope, exception being on the payload sent from the server, which get's deleted on the first getCall made) |
| 58 | + |
| 59 | +## Flow |
| 60 | + |
| 61 | +1. Create a config with this module, with a unique key and export it |
| 62 | +2. Import that config in your server side entrypoint and call setConfig at the very top, just once |
| 63 | +3. In the server to client handoff payload send the serialized public runtime config `serializedClientConfig`, this allows it to be available in Config.client |
| 64 | +4. Call `Config.client` anywhere and call `Config.server` only on the server, doing something else will throw errors |
| 65 | + |
| 66 | +## Gotchas |
| 67 | + |
| 68 | +It doesn't protect against possible runtime errors due to something relying on a server value in the client so be careful. |
0 commit comments