etalab / cra-envs

⚙️ Bundle env var in CRA at launch time!

Bundle environment variables in create-react-app at build time launch time!

Motivation

Create-react-app supports environment variable but they are bundled at build time when yarn build is run.
If we want to change anything like the URL of the backend the app should connect to, we have to rebuild, we can't ship customizable Docker image of our CRA apps.

The solution would be to be able to do:

 docker run --env FOO="xyz" my-org/my-create-react-app

Then access FOO:

• In the code like process.env["FOO"]
• In public/index.html like <title>%FOO%</title>

cra-envs does just that, in a secure, performant and type safe way.

Features

• ✅ No impact on the startup time.
• ✅ No impact on the Docker image size.
• ✅ Require no network connection at container startups.
• ✅ Secure: It only injects the envs declared in the .env file.
• ✅ It works like you are already used to. It just changes when the envs are injected.
• ✅ EJS support in public/index.html (did you know?).
  This enables for example to conditionally preload one font or another
• ✅ (Optional) Type safe: An env getter is generated so you know what envs are available.

Usecase example

Onyxia-web is a create-react-app distributed as a Docker image.

Sysadmins that would like to deploy Onyxia on their infrastructure can simply use the official Docker image and provide relevant environnement variable to adjust the theme/branding of the website to their usecase.

Here are two deployment example:

_{^{Click on the social media preview to access the websites}}

Documentation

Find 👉here👈 a demo setup of:
cra-envs + create-react-app + TypeScript + Nginx + Docker

More details on how it works

The recommended way to get started with cra-envs is to follow the instructions provided in the cra-envs-demo-app.
Now, if you want to acquire a deeper understanding what the tool does and how you can follow the following steps.

Start by installing the tool:

yarn add cra-envs 

Then declare all the allowed environment variables into the .env file of your project

Example

REACT_APP_FOO="Default value of foo"
REACT_APP_BAR=
REACT_APP_BAZ=
REACT_APP_FIZZ=

Once it's done run the script npx generate-env-getter ( Use npx generate-env-getter js if you your project don't use TypeScript)

It will generate src/env.ts ( or src/env.js) looking like:

/* 
* Automatically generated by cra-envs.
* If you wish to declare a new environment variable declare it in the .env file (prefixed by REACT_APP_)
* then run 'npx generate-env-getter' at the root of your project.
* This file will be updated.
*/
import { getEnvVarValue } from "cra-envs";

export const envNames = [
  "FOO",
  "BAR",
  "BAZ",
  "FIZZ"
] as const;

export type EnvNames = typeof envNames[number];

let env: Record<EnvNames, string> | undefined = undefined;

export function getEnv() {

    if (env === undefined) {
        env = {} as Record<EnvNames, string>;
        for (const envName of envNames) {
            env[envName] = getEnvVarValue(envName);
        }
    }

    return env;

}

(This file should be gitignored)

Now let's test it by creating a .env.local file like:

REACT_APP_BAR="Value of bar defined in .env.local"

And let's do this somewhere in our code:

import { getEnv } from "./env.ts"

console.log(getEnv());

Now if we run REACT_APP_BAZ="Value of baz passed inline" yarn start we get this in the console:

{
    "FOO": "Default value of foo",
    "BAR": "Value of bar defined in .env.local",
    "BAZ": "Value of baz passed inline",
    "FIZZ": ""
}

Now if you run yarn build then BAZ="Value of baz on the server" npx embed-environnement-variables the value of BAZ will be injected in build/index.html (or html/index.html) so that if you start statically serving the build/ dir, for example with serve -s build you will get this in the console:

{
    "FOO": "Default value of foo",
    "BAR": "Value of baz on the server",
    "BAZ": "",
    "FIZZ": ""
}

Note that on the server the environment variable names don't need to be prefixed with REACT_APP_ (they can though). Also note that the script runs very fast and thus represent virtually no overhead when starting your container.
By default embed-environnement-variables does not embed variables defined in .env.local, if you want to include them use: --includes-.env.local or -i.

The next step is to set up a clean Dockerfile where there is both node and Ngnix available.
Node for being able to run npx embed-environnement-variables and Ngnix for serving the app.
It is also important to make sure cra-envs is not bootstrapped by npx in the entrypoint.