Runtime environment variables

[kmalakoff]

Regarding this pull request around the improvements to environment variables, based on @gaearon's suggestion, I wanted to start a discussion on how to handle a docker-centric, 12 factor app-based workflow where environment variables are provided externally at runtime rather than at build time so that the exact same assets can be run in multiple environments.

Constraints / design goals mentioned is:

It's important though to note that CRA always produces static bundles, and they are expected to work in any environment regardless of server, container, etc.

In the past, I have implemented the following two solutions:

1. render environment variables into the HTML and then hoist them into an application at initialization
2. fetch environment variables from a server (for example, before creating the store and rendering the app with some static content during the initial fetch)

The first solution's benefit is that there is no delay before initial render, but with create react app dynamically modifying the html file, it becomes a little more tricky to implement since you would need to parse or search / replace within the rendered html before serving the file.

I'm just wondering if there is a better / best way to provide runtime environment variables to CRA applications and if we can get agreement on an approach, if it can be integrated into the CRA pipeline.

Thank you for all the great work and hoping for something awesome here! 🙏

[heyimalex]

Environment variables have to be compiled in because things like NODE_ENV lead to tons of dead code elimination, so whatever solution you're looking for will probably need to coexist with env vars as they are today.

And I feel like you've hit the right solution: a script tag in the head of public/index.html that defines the variables, either inline or as an external js file. You've got the tradeoffs right as well; an extra request vs a slightly more complex release-creation process. Really not hard to do today, and in my opinion out of the scope of create-react-app. What's wrong with just rebuilding for configuration changes?

But if we're brainstorming...

Maybe env vars could somehow be denoted as being dynamic/runtime injected. A prefix of REACT_APP_RUNTIME or something. They get compiled into global variable references, something like window.runtimeEnvVars.<varname>, and instead of an index.html you get an index.html.template and a little script that can combine your partial build with a .env configuration into a full release.

[kmalakoff]

Interesting and totally understand if this might be out scope for CRA.

The main problem is that when I consult, I need to tell clients who deploy via docker and 12 factor app principles to ignore the environment variable solution in CRA which is a bit confusing since one would expect that CRA's environment variables solution would meet this common use case. To be honest, I'm actually not sure of why anyone would want build time environment variables, but it could be that I've been using and advocating for 12 factor app principles to clients for too long...

In your brainstorming ideas, is there a way to inject code into the CRA index.html at runtime currently? If not, that sounds like an interesting line of potential solutions.

[pscanf]

What's wrong with just rebuilding for configuration changes?

@heyimalex: for instance if you deploy your apps using docker, having to rebuild the app for configuration changes has some drawbacks:

• you have to include node and all the build toolchain in your image
• the startup time for your container increases significantly
• your container resource requirements increase significantly

Proposal

I suggest an approach similar to the one I used for sd-builder, a tool conceptually very similar to CRA that I've built back when CRA didn't yet exist (and that I would like to discontinue in favour of CRA).

sd-builder's approach

In apps built with sd-builder, configuration is loaded from a file - app-config.js - that you include in your app's index.html. The file defines the global variable window.APP_CONFIG, which holds the configuration object.

During development, the sd-builder dev server generates the file from the variables listed in the .env file.

sd-builder also provides a command - sd-builder config - to generate the file from (scoped) environment variables.

Creating the production bundle is therefore a two-step process:

• first you run sd-builder build, that builds the app
• then you run sd-builder config, which only generates the configuration file

When deploying with docker, you'd typically run the first step when building the docker image, and the second step when running the container.

This solves the last two drawbacks listed above. It doesn't solve the first one because you still need sd-builder to generate the config file, but that could be remedied by extracting the generation logic (30 lines of js) into a separate, smaller utility (maybe even with a C/bash port to cut down on runtime dependencies).

Suggestion for CRA

The above approach could be used in CRA without touching CRA. You add app-config.js in your index.html and develop a script that:

• during development, you run before react-scripts start. The script generates app-config.js from .env, and places it in the public/ folder (I guess you should then .gitignore it)
• at "production runtime", you run before starting your static server. The script generates app-config.js from environment variables and places it in the build/ folder

However this approach has some issues:

• it's a bit hackish
• it doesn't allow to use environment variables in index.html
• it cannot be used to set process.env.PUBLIC_URL at runtime (and PUBLIC_URL feels to me like a runtime variable)

So I would suggest to bring that behaviour into CRA: in development, by making react-script start generate the config file and the configured index.html, in non-development, by providing a react-script config script that does it. (You could actually do without app-config.js, and simply embed the configuration in the index.html).

---

Thoughts? (@kmalakoff @gaearon @Timer)

[heyimalex]

Here's a build script to do this. Usage:

• Define some variables in your .env with the prefix REACT_APP_RUNTIME_
• Run the build script. It should run the regular react-script build process and create an extra file in the build directory called gen-index.js.
• Run that gen-index script with your runtime env vars set and it'll generate an index.html with those variables defined.

It's pretty hacky but should be a good proof-of-concept for how the experience could be.

• ✔️ Development mode works exactly the same as today: runtime variables are only aliased in production builds.
• ✔️ Build-time env vars are not going away, so any new runtime configuration system must coexist with what's already there. This strategy allows users to opt in without breaking the old system or creating an entirely new separate system.
• ✔️ Rebuilding the index is fast.
• ✔️ All of the static assets are still static.
• ❌ Doesn't do PUBLIC_URL. Didn't try it, haven't put any thought into it.
• ❌ It's one more thing to think about. How many people would really use this feature? How much confusion could it cause? Does this get in the way of wider uses of env vars?
• ❌ This current take is hacky, relies on string replacement/manipulation and so may not be hygenic, messes up source maps, messes up file hashes. All of that can be fixed with enough work I think. Which brings me to...
• ❌ With enough work, someone could do this safely as a separate package.

[hoolymama]

I ended up here as was struggling with this too but since found a different solution. I'd be interested to know if it violates the any best practices, 12 step principles or if there are any security concerns.

• I Set up a small express server to serve the static app, plus one api route called /config. When the app is run a json object is created with the whitelisted variables pulled from the environment, or defaults.
• In the react app I made a higher order component withConfig() that fetches from the /config route and provides the result as props to the wrapped component.
• To make this work in dev mode I set the proxy in package.json to point to the express server. This means in dev mode I have to start both the express server (npm start) and dev server (react-scripts start).

Here's a gist

[jakubknejzlik]

@hoolymama thanks for the gist. I've been struggling with this problem in few projects and IMHO it's crucial to be able to specify environment variables for configuring the application.

Although it might not be in scope for CRA, it would be nice to unify some approach and be able to use it without and further setup needed.

[adrianblynch]

I solved this for my current project, which is ejected, by conditionally passing in config via /config/env.js:getClientEnvironment():

function getClientEnvironment(publicUrl) {
  // Code...
  NODE_ENV: process.env.NODE_ENV || "development",
  PUBLIC_URL: publicUrl,
  CONFIG: process.env.NODE_ENV === "development" ? config : "" // Only for development
  // Code...
}

This fixes it for local development.

I also inject config into a script block in index.html on the server (Express or Koa).

Then in my Config component I look for config on the window object OR in process.env.CONFIG.

I then control which config to use with CONFIG_ENV=ci|staging|whatever yarn dev|serve.

It's not perfect, but it fixes it for us and we can now promote our staging build to production on Heroku without rebuilding.

[pscanf]

Update from a user

For those who might be interested, I've built a static server "specialized" for serving and configuring at runtime create-react-app apps: staticdeploy/app-server. It also allows for an easy "dockerization" of the apps.

To allow runtime configuration, it just uses an alternative configuration mechanism. So it doesn't work out-of-the-box with create-react-app, but making it work is simply a matter of adding a script tag to public/index.html, so it's not too bad.

When serving the files, I also implemented some best-match redirects to allow the app base url (PUBLIC_URL) to be configured at runtime as well.

[sr1994lu]

How about rewriting withimmutable-js?

[sazzer]

My big concern with some of the solutions is - I'd like to be able to host my app on a CDN that only serves static files, whilst at the same time I'd like to know that the software deployed to Dev, QA, PreProd and Prod are all the same.

If I'm needing to dynamically generate files on startup, that fails the CDN requirement.
If I'm needing to rebuild the entire application in order to deploy into different environments, that fails the QA/PreProd/Prod requirements.

The idea of having an app-config.js file that is deployed alongside the built application is the best I can think of so far. It means that the entire application is built once, and on deployment that file is added alongside it for deployment-specific details - such as backend URLs to call. It is another moving part to think about though, but not a very big one. It can probably be done in the Docker setup using just shell scripting as well, not needing a complex setup. Just a bunch of echo statements into a well-known filename passing in environment variables.

[jakubknejzlik]

@sazzer can you be more specific how does it fails the CDN requirement? Is it the recommendation of static content, which can be change just by changing the environment variables?

[sazzer]

@jakubknejzlik The CDNs that I've looked at serve up static files. They don't let you run server processes to dynamically generate content. This would mean that the files that are served to the browsers need to be the files that are uploaded, as-is.

What I'm really hoping for - but feeling less and less hopeful about - is a process similar to:

• Change is made to source code
• Ci system builds the code
  • CI system automatically runs "npm test"
  • CI system automatically runs "npm run build"
  • CI system automatically puts a copy of the "build" directory into our artifact repository
  • CI system automatically deploys this latest build to the Dev system
• At some point, an artifact is deployed to QA
  • The appropriate artifact is picked from the repository and deployed as-is to the QA systems
• At some point, an artifact is deployed to PreProd
  • The appropriate artifact is picked from the repository and deployed as-is to the Prod systems
• At some point, an artifact is deployed to Prod
  • The appropriate artifact is picked from the repository and deployed as-is to the Prod systems

For the backend - which is a Java app - this is really simple. The Java process can be run with system properties on a per-environment basis to provide the appropriate config - database credentials right now - but the actual files deployed are identical from one environment to the next.

For the frontend, because it's CRA which produces static files, this is not so easy.

The best I've been able to come up with so far is for the frontend deployment to be:

• The frontend artifact contents
• Another file dropped next to index.html that contains the appropriate configuration needed.

This technically means that the deployment onto each environment is not the same, but it's as close as I can make it right now. This means that I can't guarantee that the deployment to Prod will work just because it passed all of the tests at the earlier stages. (And no, technically I can't guarantee that with the backend with its environment properties, but it's a lot easier to manage and verify that. Start service, call healthcheck endpoint, on failure rollback.)

[gaearon]

Is there anything we need to do on our side for this? I don't understand from reading this issue.