Package Exports

runtime-env-cra-fallback
runtime-env-cra-fallback/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (runtime-env-cra-fallback) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Runtime-env-cra-fallback

runtime-env-cra-fallback allows falling back to .env values in case environment key cannot be found in process.env

A runtime environment handler for React.js apps that have been bootstraped using create-react-app.

Usage
Requirements
CLI Options
Using in a Typescript app
Usage in Docker
Examples
Test Coverage
Contributors

Usage

The runtime-env-cra-fallback 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-fallback 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-fallback

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-fallback --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-fallback --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-fallback --help | -h

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

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

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

$ runtime-env-cra-fallback --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-fallback && 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!