0.2.4 • Public • Published


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


    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.


    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;\""]


    • 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





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


    npm i runtime-env-cra

    DownloadsWeekly Downloads






    Unpacked Size

    169 kB

    Total Files


    Last publish


    • khris-