Managing .env variables for provisional builds with Create React App

When developing web applications by using Create React App, developers get NODE_ENV=development on their local environment and NODE_ENV=production on the production build by default. And, modifying NODE_ENV is forbidden. According to the Create React App, this is an intentional setting to protect the production environment from a mistake/accident deploying.

You will be able to see scripts like below in package.json after creating your web app.

// package.json
scripts: {
  "start": "react-scripts start", // `NODE_ENV` is equal to `development`.
  "build": "react-scripts build", // `NODE_ENV` is equal to `production`.
  ...
}

If you create or already have .env.development and .env.production in the root of your project, these files will be used for running each script. npm start will pick up .env.development, and npm build will use environment variables in .env.production.

-
What if you want to setup .env.staging?

This article will show you how to manage environment variables for provisional builds.

Let's dive into that! Oh, if you do not have any experiences of CRA, please Getting started

-

Story

Imagine that your project will have three separated provisional environments; development, staging, and production. Each environment is using different API endpoints. In addition to that, the project may require a REACT_APP_CUSTOM_NODE_ENV. This is because NODE_ENV will always be production for the build regardless.

-

Goal

• Create .env.development, .env.staging, and .env.production.
• Configure environment viriables for each build.
• Modify scripts in package.json

-

Getting started

Step 1.

Thankfully, dotenv comes out of box. Let's create .env files under the root folder to manage environment variables. The files are .env, .env.development, .env.staging, and .env.production.

• .env - Keep all common/shared environment variable
• .env.development - Variables are used for the local development
• .env.staging - Variables are used for the staging build
• .env.production - Variables are used for the production build

For example;

#.env
REACT_APP_DOC_TITLE = "Document title"

//.env.developement
REACT_APP_API_ENDPOINT = "https://development-api.endpoint.com/"

#.env.staging

# NODE_ENV will always be set to "production" for a build
# more details at https://create-react-app.dev/docs/deployment/#customizing-environment-variables-for-arbitrary-build-environments
REACT_APP_CUSTOM_NODE_ENV = "staging"
REACT_APP_API_ENDPOINT = "https://staging-api.endpoint.com/"

#.env.production
REACT_APP_API_ENDPOINT = "https://api.endpoint.com/"

NOTE: The prefix REACT_APP_ is required when creating custom environment variables.

.env.development and .env.production

As a default behavior, those files will be served with no configuration. You do not even have to update scripts in package.json

.env.staging

Here is the main focus of this post. To target .env.staging file for the staging build, we need a library to achieve this.

1- Let's install env-cmd. This library will will help us on using/executing a selected environment file. See more detail

// execute command below at the root of project
$ npm install env-cmd --save
or
$ yarn add env-cmd

2- Add a script in package.json like below.

// package.json
scripts: {
  "start": "react-scripts start", // `NODE_ENV` is equal to `development`.
  "build": "react-scripts build", // `NODE_ENV` is equal to `production`.
  "build:staging": "env-cmd -f .env.staging react-scripts build", // `NODE_ENV` is equal to `production`.
  ...
}

3- Finally, test your build:staging script.

-

Conclusion

The intention of this technique is to use different custom environment variables for many provisional environments without ejecting the default CRA configs.

-

Resources

• Customizing Environment Variables for Arbitrary Build Environments

• Adding Custom Environment Viriables

• dotenv

Special Thanks

• @foxbit19 - found env-cmd version 8.x requries additional argument to link to the custom env file.
• @j6000 - pointed out NODE_ENV for the build will always be set to "production" regardless.