How To Deal With Custom .env Files in React

When developing a React application, a common scenario is to have three deployment environments:

Local: for local development.
Staging: an online mirror of the production environment.
Production: the live application that serves end-users.

Your architecture may also have other deployment environments, such as a Testing, Development, or Pre-Production environment.

This means that your application is likely to require at least three different .env files. However, a Create-React-App application only supports a limited and predefined set of .env files.

Let’s now learn how to set up multiple custom .env files for your React application.

Setting Up Multiple Custom .env Files in a Create-React-App Application

Create-React-App applications use react-scripts. If you are not familiar with how .evn files work in react-scripts, take a look at the “What other .env files can be used?” section of the Create React App documentation. There, you can learn what .env files react-scripts supports and how it uses them.

Now, let’s learn how to set up a custom .env.staging file in your React application. Note that the following approach can be easily extended to any other custom .env file. In addition, this solution allows you to have multiple custom .env files.

1. Getting Started

A Create-React-App application is initialized with the following scripts section in the package.json file:

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}

react-scripts supports only a specific set of .env files. These .env files are used at build time, when deploying your application.

So, if you want your Create-React-App application with custom .env files to build correctly, you need to customize the build command. In detail, you need to replace it with a custom build script. This way, you can overcome the react-scripts limitations when it comes to .env files.

2. Creating a Custom Build Script

First, create a build.sh file in the root directory of your project. Initialize it as follows:

# removing the .env.local file because 
# react-scripts uses it if it is present
rm -f ./.env.local

# if this is the staging deployment environment
if test "$ENV" = "staging"
  then
    # removing the .env.production file 
    # because otherwise react-scripts would use it
    # as the default .env file
    rm -f ./.env.production
    
    # renaming ".env.staging" to ".env.production" so that
    # react-scripts will use it as .env file
    mv ./.env.staging ./.env.production
  fi

# building the React application
npm run react-scripts build

Here, .env.local is deleted and .env.production is replaced by .env.staging when the ENV environment variable is equal to “staging”. This way, react-scripts build will see the custom .env.staging file as .env.production, and use it when building the application.

Note that you can extend this approach to several environment variables simply by repeating the if ... fi logic and changing the test condition.

Now, you have to update package.json to make it call the custom build.sh script on build. You can achieve this as follows:

"scripts": {
  // ...
  "build": "bash build.sh",
  // ...
}

When you run npm run build, the build.sh file will be launched. Since buld.sh contains the react-script build command, the application will be built just as before. But with the .env file management logic defined before the react-script command.

3. Setting the ENV Environment Variable in Your Deployment Servers

At this point, all you have to do is set the ENV environment variable in your staging deployment server. On Linux, you can achieve it with the following command:

export ENV=staging

Et voilà! You just learned how to use custom .env files in your Create-React-App React application. Note that you can configure custom .env files also in Next.js.

Conclusion

In this article, you learned how to configure your React application to support multiple custom .env files. Create-React-App applications come with some limitations when it comes to the .env files. Therefore, if you have more deployment environments other than those expected by react-scripts, you need to implement custom logic to enable support for custom .env files. Here, you learned how to do so.

Thanks for reading! I hope you found this article helpful.