Runtime Configurations with React
matt_catalfamo
•May 1, 2024
(Source/Credits: https://dev.to/matt_catalfamo/runtime-configurations-with-react-22dl)
title: Runtime Configurations with React published: true description: tags: react, SPA config, runtime, configurations
Most of the time using custom build time environment variables are suitable but runtime variables can be valuable in addition to or in place of environment variables.
Runtime configurations or variables, can be beneficial when you need to change a configuration at run time. Some examples of variables you could load at runtime is theme data or api urls.
Do not store any secrets (such as private API keys) in your environment or runtime variables!
Why runtime variables?
- Build app only once and deploy the same build to multiple environments (i.e. dev, qa, prod)
- Configurations can be changed/updated after the app is deployed
- Load configurations from an external source
- Save time - Build pipelines can take long periods of time some with many steps (i.e. infrastructure steps, build steps, tests, etc). Loading configurations during runtime can help reduce the amount of times your app is built.
How do runtime variables work?
Runtime variables get loaded into the browser's window object when the index.html of a single page application gets loaded.
In the <head> or <body> of the html file we can run a Javascript snippet that sets up the configurations on the window object.
Javascript code in the index.html file will get loaded synchronously from top to bottom as long as the async flag is not present. By placing the code to load our snippet before the main bundle it can be guaranteed that the values will be set on the window object and accessible when your main javascript bundle is loaded.
Let’s look at how this can be accomplished.
Create a new file called runtime-config.js and setup some variables
``` // runtime-config.js window['runConfig'] = { apiUrl: 'test.com/api' }
```
To load the script in the index.html file add the script tag to the file inside either the <head> or <body> tag. If you are starting with Create React App the file will be located at <project_root>/public/index.html
<script src="%PUBLIC_URL%/runtime-config.js"></script>
``` // index.html
<!-- runtime config -->
<script src="%PUBLIC_URL%/runtime-config.js"></script>
<!-- runtime config -->
<title>React App</title>
```
How to use in a React component
To access the variables that are setup in the runtime-config file, from your app files you can reference the window object.
window['runConfig']
Example usage in a React component:
``` export const MyComponent = () => { const { apiUrl } = window['runConfig']; return (
```
Full Example:
https://github.com/mattcat10/react-runtime-config
Notes: - Don't use runtime configurations if your configurations are really large. They are loaded synchronously and could slow down your initial load time of your app
- This post explains how to use runtime configurations in a react app, but the same concept can be applied to any SPA framework.
Comments section
joe_black_4752a0e6d658ff5
•May 1, 2024
Does anybody have tips on testing this with Jest?
mahdigb05
•May 1, 2024
thanks for the article !!, I only have one question I tried this methode but had a small issue. when I open a new tab (when clicking a link for example) the scripts doesn' get executed and would have undefined error when trying to read the config object.
amanchaudhary1998
•May 1, 2024
Can you help me how to configure for dev, prod and staging at the runtime and how BUILD_ENV get the environment variable
ENV_CONFIG = ${node -p -e "JSON.stringify(require('./${CONFIG_BASE_PATH}/${BUILD_ENV}.config.json'))")
adash
•May 1, 2024
Thanks Man!
This is exactly what I needed!
priya0607jain
•May 1, 2024
Thanks for the great article! Finally, after days of headache, it helped me understand the things about "build once, deploy everywhere".
Just one thing though, as @idjuraj suggested below, on making variables specific per env, you said
during the deployment pipeline as a step, calling a bash script to read in the proper environment json file and create the runtime-config.js file., can this be also applied to when we push the code to pipleine? I mean, I have a git pipeline that automates the build process as soon as the code is pushed. So is there any way that I can define the environment into that pipeline (Inside the yml file) ? So that build can be created automatically for different envs?idjuradj
•May 1, 2024
Great article! Do you have any advice on how to make these variables specific per environment?
matt_catalfamo Author
•May 1, 2024
Thanks for the reply. Considering that these are runtime configs, one method you can use is creating the
runtime-config.jsfile as part of the deployment pipeline.I like to keep the config files per environment organized in json in my repository, so one method that I like to use is to have a different json file per environment (dev.config.json, stg.config.json, prod.config.json) making sure the file name is the same as the environment name and keeping the property names consistent
Ex dev json:
``` { "apiUrl": "testing.mattcat.dev" }
```
Enter fullscreen mode
Exit fullscreen mode
Ex prod json:
``` { "apiUrl": "prod.mattcat.dev" }
```
Enter fullscreen mode
Exit fullscreen mode
Then during the deployment pipeline as a step, calling a bash script to read in the proper environment json file and create the
runtime-config.jsfile.The bash script looks something like this:
```
!/bin/sh -e
CONFIG_BASE_PATH="./app/configs"
touch "./app/env-config.js" # create generic file ENV_CONFIG=$(node -p -e "JSON.stringify(require('./${CONFIG_BASE_PATH}/${BUILD_ENV}.config.json'))") # read proper json file
echo "window.envConfig = $ENV_CONFIG" >> "./app/env-config.js" # write json to generic file
```
Enter fullscreen mode
Exit fullscreen mode
Calling it like this during your deployment pipeline
BUILD_ENV=stg ./config-expansion.shI am sure you can find other ways to generate the run-config.js file but this is one method that has worked for me in the past.
hey_yogini
•May 1, 2024
Is there any way, to use this same configuration for local setup? This worked for runtime but localhost could not find them!
matt_catalfamo Author
•May 1, 2024
Hey,
If you are using webpack, in your local webpack configuration you can create the file using the create-file-webpack plugin (npmjs.com/package/create-file-webpack)
Then your plugin configuration would look something like this:
`` plugins: [ new CreateFilePlugin({ path:your public folder, fileName: 'runtime-config.js', content:window.runConfig=${JSON.stringify( { apiUrl: 'test.com/api' } )};`, }), ]```
And if you wanted to load your config from a file you can import it like:
``` const myConfigVar = require('./your-config.json');
```
and replace
{ apiUrl: 'test.com/api'}withmyConfigVarponder6168
•May 1, 2024
Solved my issue. Thanks!