@xtreamsrl/react-config v0.4.4

@xtreamsrl/react-config

This package exposes utility functions and interfaces to easily handle environment variables. It is agnostic with respect to the bundler used in the project. It also allows runtime configuration injection using an env.js file avoiding the need to rebuild the application for each environment.

Installation

npm install @xtreamsrl/react-config

Usage

After having defined the environment file as needed, in order to configure project variables, augmentation must be used to fill the Config and EnvData interfaces that are exported empty from the library.

Create a file config.d.ts

import '@xtreamsrl/react-config';

declare module '@xtreamsrl/react-config' {
  export interface Config {
    env: string;
    isLocal: boolean;
    version: string;
    //...
  }

  export interface EnvData {
    REACT_APP_ENV: string;
    REACT_APP_VERSION: string;
    //...
  }
}

Notice: while using webpack to add custom env vars it is neccessary that their starts with REACT_APP_, if you are using Vite the prefix is VITE_. This is a mechanism used to prevent accidentally leaking env variables to the client. For example, you will have to use VITE_REACT_APP_ENV instead of ENV if you want that variable to be exposed to your processed code.

Once the interfaces are populated it is possible to configure the variables. Configure them once in the whole application.

configureEnvVars(env => ({
  env: env.REACT_APP_ENV,
  isLocal: env.REACT_APP_ENV === 'local',
  version: env.REACT_APP_VERSION,
}))

The next step depends on the bundler used in the project.

Nx project

Create the env.js file in the src folder, these are the variables that will be actually used in the application:

window.__env__ = {
  REACT_APP_ENV: 'enterprise',
  REACT_APP_VERSION: '1.0.0',
};

In the project.json file, add the path to the env.js file to the assets:

{
  "assets": [
    "apps/my-app/src/assets",
    "apps/my-app/src/favicon.ico",
    "apps/my-app/src/env.js"
  ]
}

In this way the env.js file will be copied to the dist folder during the build phase.

Vite project

Create the env.js file in the public folder (frontend/public/env.js), this empty environment will be automatically populated and loaded in the application with the needed environment variables:

window.__env__ = {};

In this way the env.js file will be copied to the dist folder during the build phase.

Webpack project

TODO: add instructions for setting up with Webpack

The following instructions are again the same for all bundlers.

Add the reference to the env.js file in the index.html file:

    <script src="env.js" type="application/javascript"></script>

And now you are ready to use environment variables where needed.

export function App() {
  const vars = useEnvVars();
  console.log(vars)
  return <div>{vars.env}, {vars.isLocal}</div>
}

There is also to access the variables directly from the config object.

import { config } from '@xtreamsrl/react-config';

const isLocalString = config.isLocal ? 'local' : 'not local';

The reason behind the usage of this library is avoiding the building of the application for each environment, but instead having a single build that can be deployed in different environments.

Who we are