The runtime-env-cra package was meant to be used in Docker or VM based environments, where you have full control over how your application will start. Sadly, runtime-env-cra can not be used if you are using S3 or another static file serving solution.

Supported node.js versions due to yargs is 12 or greater
Installation

$ npm install runtime-env-cra

Add the following to public/index.html inside the <head> tag:

<!-- Runtime environment variables -->
<script src="%PUBLIC_URL%/runtime-env.js"></script>

Modify your start script to the following in your package.json:

...
"scripts": {
  "start": "NODE_ENV=development runtime-env-cra --config-name=./public/runtime-env.js && react-scripts start",
  ...
}
...

If you are on windows, you need to use cross-env

"scripts": {
  "start": "cross-env NODE_ENV=development runtime-env-cra --config-name=./public/runtime-env.js && react-scripts start",
  ...
}

The script parses everything based on your .env file and adds it to window.__RUNTIME_CONFIG__. If you pass NODE_ENV=development for the script, it will use the values from your .env, but if you provide anything else than development or nothing for NODE_ENV it will parse environment variables from process.env. This way you can dynamically set your environment variables in production/staging environments without the need to rebuild your project.

Requirements

This script uses your .env file by default to parse the environment variables to window.__RUNTIME_CONFIG__, so be sure to have one in your project! After modifying the start script and public/index.html described in the section above, you should be good to go!

CLI options

Display the help section.

$ runtime-env-cra --help | -h

Relative path and file name that will be generated. Default is ./runtime-env.js

$ runtime-env-cra --config-name | -cn

Relative path and name of your env file. Default is ./.env

$ runtime-env-cra --env-file | -ef

Typescript usage

Create ./src/types/globals.ts file and pase the following (modify the __RUNTIME_CONFIG__ properties to match your environment):

export {};

declare global {
  interface Window {
    __RUNTIME_CONFIG__: {
      API_URL: string;
      NODE_ENV: string;
    };
  }
}

Add "include": ["src/types"] to your tsconfig.json.

{
  "compilerOptions": { ... },
  "include": ["src/types"]
}

Usage in Docker

You must have an example of your env layout. A project usually have a .env.example which represents that and will not contain any sensitive information. Inside a docker container we can lean on the .env.example. Make sure your .env.example is always up to date!

Using in an alpine based container

# copy .env.example as .env to the container
COPY .env.example .env

# install nodejs & npm
RUN apk add --update nodejs
RUN apk add --update npm

# install runtime-env-cra package
RUN npm i -g runtime-env-cra

# start the app with the following CMD
CMD ["/bin/sh", "-c", "runtime-env-cra && nginx -g \"daemon off;\""]

Examples

Create react app with typescript template, including Dockerfile and docker-compose. (source)
Create react app without typescript, including Dockerfile and docker-compose. (source)

Test coverage

-------------------|---------|----------|---------|---------|-------------------
File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------------|---------|----------|---------|---------|-------------------
All files          |     100 |      100 |     100 |     100 |
 generateConfig.js |     100 |      100 |     100 |     100 |
 utils.js          |     100 |      100 |     100 |     100 |
-------------------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        1.751 s

Contributors

_kHRISl33t

_peteyycz

_seanblonien

If you find a bug or have a question about the usage, feel free to open an issue!

Keywords

FAQs

What is runtime-enviroment?

Is runtime-enviroment well maintained?

Package last updated on 25 Jan 2023

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

runtime-enviroment

Runtime-env-cra

Usage