How To Deal With Custom .env Files in Next.js

When developing a Next.js website, a common scenario is to have three deployment environments:

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

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

So, your Next.js application is likely to need at least three different .env files. Yet, a Create-Next-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 Next.js application. Note that you can configure custom .env files also in React.

Configuring Multiple Custom .env Files in a Create-Next-App application

Let’s learn how to set up a custom .env.staging file in your Next.js application. The approach you are about to see can be easily extended to any other custom .env file. Plus, this method allows you to have multiple custom .env files.

1. Initial Configuration

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

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start"
}

next supports only a specific set of .env files. Such .env files are employed at build time, when deploying the Next.js application.

Consequently, if you want your Create-Next-App application with custom .env files to build correctly, you have to change the build command. Specifically, you need to replace it with a custom build script. In this way, you can overcome the aforementioned limitations related to .env files.

2. Defining a Custom Build Script

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

# removing the .env.local file because 
# next 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 next would use it
    # as the default .env file
    rm -f ./.env.production
    
    # renaming ".env.staging" to ".env.production" so that
    # next will use it as .env file
    mv ./.env.staging ./.env.production
  fi

# building the Next.js application
npm run next build

Here, .env.local is removed and .env.production is replaced by .env.staging when the ENV environment variable is equal to “staging”. In this way, next will see the custom .env.staging file as .env.production, and utilize it when building the application.

Keep in mind that you can easily extend this solution to multiple environment variables by repeating the if ... fi logic and modify the test condition accordingly.

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

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

When running npm run build, the build.sh file will be executed. buld.sh contains the next build command, the application will be built exactly as before. But with the .env file management logic defined before the next build command.

3. Setting the ENV Environment Variable in Your Deployment Servers

Now, you have to set the ENV environment variable in your staging deployment server. On Linux, you can do it with the command below:

export ENV=staging

Congrats! You just learned how to use custom .env files in your Create-Next-App Next.js application.

Conclusion

In this article, you learned how to set up your Next.js application to support multiple custom .env files. Create-Next-App applications come with some limitations when it comes to the .env files. So, if you have more deployment environments other than those expected by next, you have to define custom logic to support custom .env files. Here, you had the opportunity to see how to do it.

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