spa-env
v1.2.9
Published
Script for embedding server variable in Vite or CRA apps without having to rebuild.
Downloads
5
Maintainers
Readme
Motivation
Vite and create-react-app both have support for environnement variables (in vite/in cra)
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 SPA apps.
The solution would be to be able to do:
docker run --env FOO="xyz" my-org/my-vite-app
Then access FOO
:
- In the code like
process.env.FOO
orimport.meta.env.FOO
- In
index.html
like<title>%FOO%</title>
spa-env
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.
- ✅ Extends the existing standard in place without breaking them, your dev environnement won't be affected.
- ✅ Secure: It only injects the env declared in the
.env
file. - ✅ It works like you are already used to. It just changes when the env are injected.
This enables for example to conditionally preload one font or another - ✅ Type safe: An env getter is generated so you know what env are available.
- ✅ CRA only: EJS support in
public/index.html
(did you know?).
Why this instead of import-meta-env?
Because spa-env is fully compatible with the way Vite and CRA manage environments variable.
It doesn't overwrite the existing standard, it extends it by enabling you to take control over when the ENV are injected.
This means that your development environnement, your storybook, your testing framework won't be affected at all by the fact you are using this module.
Project starter
Vite
spa-env
+ Vite
+ Nginx
+ Docker
👉 https://github.com/codegouvfr/spa-env-vite-starter
Create React App
spa-env
+ create-react-app
+ Nginx
+ Docker
👉 https://github.com/codegouvfr/spa-env-cra-starter
Manual setup
Start by installing the tool
yarn add spa-env
Then declare all the allowed environment variables into the .env
file of your project
Example with Vite:.env
VITE_FOO="Default value of foo"
VITE_BAR=
VITE_BAZ=
VITE_FIZZ=
Example with CRA:
.env
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 spa-env.
* 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 "spa-env";
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:
VITE_BAR="Value of bar defined in .env.local" # Or REACT_APP_BAR= if in CRA
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-env
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-env
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-env
and Ngnix for serving the app.
It is also important to make sure spa-env
is not bootstrapped by npx
in the entrypoint.
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: