[RFC] Env Variable Loading for Different Environments

[flybayer]

Problem

Apps have different runtime environments like test and staging that require different environment variables.

The current Next.js env file loading as introduced in this RFC is too restricting and confusing.

1. Next.js doesn't allowing manually specifying the NODE_ENV
2. Next.js supports .env.test but NODE_ENV=test next build fails, which is confusing
3. Even if we could specify NODE_ENV, Next.js doesn't currently load files like .env.staging (unlike dotenv-flow for example)

This is a very common confusion and complaint: #12077, #17032, #19046, #12737, #12772, #9123, #22755, #12077, #14609, #14240, #18253, #10129

Proposed Solution

1. Add a new -e ENVIRONMENT_NAME flag to next dev, next build, and next start
   • Example: next dev -e staging would load .env.staging, .env, etc
2. Add APP_ENV as an official replacement of NODE_ENV for application environment
   1. Defaults:
      1. APP_ENV=development for next dev
      2. APP_ENV=production for next build and next start
   2. You can manually set APP_ENV before invoking the CLI.
      1. Example: APP_ENV=staging next start
3. Upgrade @next/env to support loading files for any environment like .env.staging

As you can see by browsing through the issues linked above, the APP_ENV pattern is one used by many of us and is also the official recommendation (source). But how to implement that is still left to the user with no good solution.

Breaking Changes?

None based on official behavior which is that you can't use NODE_ENV. That said, NODE_ENV=test next start was working in the past. However that no longer works, see #25491.

To aid users who have been relying on .env files being loaded by NODE_ENV, we could optionally still use NODE_ENV for loading files if it's present and neither -e or APP_ENV is set.

Downsides?

I see zero downside for adding the -e flag.

For automatically loading .env files based on APP_ENV, it's possible someone is using APP_ENV for something totally unrelated and this could produce some unexpected behavior. That said, I think it's safe to say most who are using APP_ENV with Next.js are using it for exactly this purpose. For example, my current code sets APP_ENV=production inside .env.production.

Alternates

Only adopt -e or APP_ENV instead of both.

Use --env instead of -e

Current Workarounds

Manually

Manually load the correct .env files via some hand rolled scripts

Via next.config.js

APP_ENV=staging next build && APP_ENV=staging next start

// next.config.js
require('dotenv-flow').config({
  node_env: process.env.APP_ENV || process.env.NODE_ENV || 'development'
});

const env = {}
Object.keys(process.env).forEach((key) => {
  if (key.startsWith('NEXT_PUBLIC_')) {
    env[key] = process.env[key]
  }
})

module.exports = {
  env
}

[dawnofmidnight]

[curiousercreative]

an env variable (such as APP_ENV) can be used to accomplish this just the same, no? Examples of the two are below, both seem to satisfy your use case:

APP_ENV=staging npm run build
npm run next build -- -e staging

The benefit of the env variable is that Vercel or another platform can more universally supply it the same as any other env variable.

[chrisj-back2work]

Exactly

[haris-aqeel]

dotenv-flow: "NEXT_PUBLIC_FIREBASE_API_KEY" is already defined in process.env and will not be overwritten

[mattcarlotta]

I'd like to offer one more additional solution: Loading from a configuration file.

Working Demo
Installation
Proposal (Pros and Cons)

[hershmire]

Would NextJS still be managing NODE_ENV internally for dropping dead code and producing an optimized build?

---

This RFC would help solve the current limitation of managing ENV vars for custom application environments but still doesn't take into account some other (seemingly large) limitations:

Robust configuration management solution
Relying on only environment variables (.env) to manage configuration isn't feasible for most large enterprise applications where you most likely need to manage larger nested objects instead of just strings per environment. Next.js and CRA's current solution seems only viable for smaller applications. Maybe the the runtime configuration is intended for this need but if used, it seems to bring drawbacks such as incompatibility with Automatic Static Optimization. This thread explains this point a bit more.

Tied to the build execution
Another limitation is that the configuration is tied to Next's build step which makes it impossible to follow a common CI practice of build once, deploy to any number of environments. Unless I've missed something in the docs, any environment we support needs to rerun the build before we can deploy the app so the bundle can store any client-side configuration. I originally thought publicRuntimeConfig was to help solve this problem but that also seems to be tied to the build as it will store that configuration in .next/required-server-files.json at build time. More discussion on this general problem.

[hershmire]

@flybayer How can I see Automatic Static Optimization get disabled when using runtime configuration? My assumption was that during build time, my client pages wouldn't compile to HTML files but as I'm using runtime config, that's not the case. I'm also not seeing any NextJS logs during build time notifying me that Automatic Static Optimization is turned off. Maybe because my page is partially static and then the rest that requires user data is CSR?

[eric-burel]

It's just that per the doc, this feature makes no real sense nowadays, you have no benefit over just using a normal JS object and importing it and instead you even lose a feature. I've tried to ask around but never seen a legitimate use case in the recent versions of Next, so my conclusion is that it's more a relicate than anything else. But of course there might be use cases that I just don't know about.

[mattcarlotta]

Relying on only environment variables (.env) to manage configuration isn't feasible for most large enterprise applications where you most likely need to manage larger nested objects instead of just strings per environment.

Excuse me if I'm being naïve, but couldn't something like this nested configuration:

{
  "public": {
    "title": "Your site title",
    "tagline":"Your site tagline",
    "logoUrl": "http://placekitten.com/250/80",
    "logoHeight": "80",
    "logoWidth": "250",
    "faviconUrl": "/favicon.ico",
    "language": "en",
    "locale": "en",
    "twitterAccount": "foo",
    "facebookPage": "http://facebook.com/foo",
    "googleAnalytics": {
      "apiKey": "foo123"
    },
    "backoffice": {
      "enabled": true
    },
    "apolloSsr": {
      "disable": false
    }
  },
  "defaultEmail": "[email protected]",
  "mailUrl": "smtp://username%40yourdomain.mailgun.org:[email protected]:587/",
  "oAuth": {
    "twitter": {
      "consumerKey": "foo",
      "secret": "bar"
    },
    "facebook": {
      "appId": "foo",
      "secret": "bar"
    }
  },
}

Be simplified to:

NEXT_PUBLIC_TITLE=Your site title
NEXT_PUBLIC_TAGLINE=Your site tagline
NEXT_PUBLIC_LOGO_URL=http://placekitten.com/250/80
NEXT_PUBLIC_LOGO_HEIGHT=80
NEXT_PUBLIC_LOGO_WIDTH=250
NEXT_PUBLIC_FAVICON_URL=/favicon.ico
NEXT_PUBLIC_LANGAUGE=en
NEXT_PUBLIC_LOCALE=en
NEXT_PUBLIC_TWITTER_ACCOUNT=foo
NEXT_PUBLIC_FACEBOOK_PAGE=http://facebook.com/foo
NEXT_PUBLIC_GOOGLEANALYTICS_APIKEY=foo123
NEXT_PUBLIC_BACKOFFICE_ENABLED=true
NEXT_PUBLIC_APOLLO_SSR=false
DEFAULT_EMAIL[email protected]
MAIL_URL=smtp://username%40yourdomain.mailgun.org:[email protected]:587/
OAUTH_TWITTER_CONSUMERKEY =foo
OAUTH_TWITTER_SECRET=bar
FACEBOOK_APPID=foo
FACEBOOK_SECRET=bar

Due to how .env's are loaded in Next, if any of these ENV variables are static, then they can be placed within .env (no environment extension) to be shared across all environments (production, development and test). Then you can override these variables per environment via .env[mode] and/or .env[mode].local. For example, let's say the development environment utilizes the above configuration, but also overrides the DEFAULT_EMAIL while adding to the base configuration:

env.development:

DEFAULT_EMAIL[email protected]
NEXT_PUBLIC_BASEURL=http://localhost:3000

Now env.development is loaded first, then .env is loaded second, which combines the two configurations (DEFAULT_ENV won't be overridden by the base configuration because .env.development was imported/assigned to the process first). Therefore, you don't need to repeat configuration properties, unless you're overidding them.

The other advantage to this flat object approach is that it allows for quick interpolation across properties since it doesn't require traversing a heavily nested JSON object:

LOGO_DOMAIN=placekitten.com
LOGO_HEIGHT=80
LOGO_WIDTH=250
LOGO_URL=https://$LOGO_DOMAIN/$LOGO_WIDTH/$LOGO_HEIGHT

One could then argue about importing a file; however, importing a file is asynchronous and Next would be required to wait for the file to be imported before spinning up the client/server; otherwise, you'll have a racing condition. Alternatively, you could synchronously read a file, but even then, you run into a few more downsides...

Some more additional downsides to using a nested JSON object would be that your code is assuming that process.env[nestedObj] would be a defined property, is an object and contains a specific property name; otherwise, you'll crash your application. Now if this JSON object becomes even more nested, then it's even more logic to make sure you're not destructuring or trying to reference a nested property that may or may not exist.
In addition, as the object becomes more nested and more complex, this becomes a pain to share configs across environments, because overriding/including one or more properties within a heavily nested object can become quite verbose:

// const { readFileSync } = require("fs");
const currentConfig = require("./config.json");

// const currentConfig = readFileSync("./config.json");

// assuming immutable
const config =
  process.env.NODE.ENV === "development"
    ? {
        ...currentConfig,
        public: {
          ...currentConfig.public,
          googleAnalytics: {
            ...currentConfig.googleAnalytics,
            secret: "bar",
          },
        },
        oAuth: {
          ...currentConfig.oAuth,
          twitter: {
            ...currentConfig.oAuth.twitter,
            secret: "foo",
          },
        },
      }
    : config;

return config;

So, more overhead logic/code for essentially the same end result.

---

A real-world limitation to the current implementation of loading .env.* files would be dynamic values that need to be acquired before build/runtime.

However, a workaround for local or remote files might be interpolating properties by spawning a child process and running some bash commands (not supported by dotenv/dotenv-expand and may be OS dependent, but here's an example):

PACKAGE_VERSION=$(cat package.json | grep 'version' | sed -r 's/version//g; s/[^[:alnum:].]//g;')
NEXT_VERSION=$(curl -s https://raw.githubusercontent.com/vercel/next.js/canary/packages/next/package.json | grep 'version' | sed -r 's/version//g; s/[^[:alnum:].]//g;')

However, even this would not be very practical for many dynamic values.

That said, for dynamic values, I'd argue that they should not be a part of the process.env, but instead be fetched during buildtime/runtime as needed.

[hershmire]

What you proposed above as a flattened set of values for .env can work but only to a certain extent. The values are limited to only strings. Some configuration needs will require other JS primitives such as arrays or objects. I'm not proposing .env or this RFC support that. Apologies if it came across that way. I'm simply stating that there are other more complex configuration needs for larger applications where relying only on environment variables and having to build the app per environment seem like big limitations and possible deal breakers for some companies. Maybe off topic for this particular discussion, but found it relevant and worth noting as I see this brought up by others in various other threads but have not found a definitive response to these concerns.

[eric-burel]

@hershmire At Aplines we do parse those values, so we allow JSON objects and arrays. We have an intermediate JS file, whose role is to validate environment variables and turn them into a typed JSON object, that it then exports (for the NEXT_PUBLIC variables at least).
Agreed, this is less intuitive, and at first I was really bothered by the lack of file based config in Next, but it's not really a huge technical blocker more a developer experience matter.

[eric-burel]

It would be nice to be able to fetch the current environment from .env or .env.local files. So the APP_ENV seems more relevant than the command-line argument approach, as you can define this variable in the main generic .env file to trigger the loading of a second specific .env.whatever file.

The problem with command-line argument is that it ends up being hard-written in your package.json which is annoying, it's always better to allow loading from environment or a file since those are "meta" to the code repository.

[eric-burel]

Slightly related to this feature: I have trouble loading configuration variables from .env.test in Cypress open mode, using const { loadEnvConfig } = require("@next/env"); in a plugin => it only allows a binary "production" vs "development" value.
In Cypress run mode, it will load from .env.test, whatever value I set. It's not very clear what happens.

[nandorojo]

I think solution 1 is the correct move. NODE_ENV doesn't necessarily indicate the environment your app is running.

For instance, we run a production version of our app in sandbox mode (using a test database). I still expect NODE_ENV=production, but I want BACKEND_ENV=sandbox (I'm fine with changing this BACKEND_ENV's name here).

I think we should keep NODE_ENV as is, while allowing us to set an --env variable so that we can customize the .env path.

I find the current .env.development and .env.production to not fit my use-case at all and be very confusing. I don't want different envs if I'm coding vs deploying: I want different ones based on sandbox vs live.

[curiousercreative]

Thanks @flybayer for the detailed RFC and sharing. As correctly pointed out by @eric-burel, I think an env variable is a more universal solution. Prior to finding this RFC, I opened this PR which shows how this might be implemented (I chose DOT_ENV as the env var)

[zmarty]

We have multiple beds for our product, not only dev and production. For example we have a test bed, and maybe we have multiple production environments in different datacenters, etc.. Each such bed has different values for the configs. The current environment variables implementation in next.js is too restricting. This RFC would probably solve the problem for us.

[leerob]

Thank you for opening this discussion!

When Next.js introduced .env support, we followed the standard set by those before us like Rails and Create React App. This RFC would diverge from the .env path.

Can you provide examples where this solves setting NODE_ENV? Wouldn't using NEXT_PUBLIC_APP_ENV solve the issue you're describing, and be properly tree-shaken? We might just be missing docs for this example.

[curiousercreative]

@leerob for our use, not secrets. I'm sure some are committing secrets to their .env.production files, but I can't imagine that should weigh on this RFC.

[flybayer]

@leerob correct, primarily for non-secrets but I also use this approach for local only secrets.

So as example for running an app locally in production mode with production secrets, I put the secrets in .env.production.local (git ignored). In the cloud, these are set via the cloud provider.

[eric-burel]

Regarding secrets, I also use .env.production for documentation purpose: I list all the variables necessary for the app to run, but without value. This helps our Devops to know which value he must absolutely set when deploying the app.
Locally, I set them in .env.production.local on my dev machine only, outside git of course, in order to being able to simulate any of our environment (local (=development), staging and production) on my computer.
We then have a second layer that checks programmatically if all the mandatory variables at app startup, in _app.js, for more robustness.
This RFC would simply allow us to have a .env.staging, in addition to .env.production, with the very same usage but for an additional environment.

[giuseppeg]

While setting up E2E tests I found myself wanting to override some ENV vars (NEXTAUTH_URL because I assign a random port to every test/app). I guess it'd be nice enough to be able to override them in next.config.js (I tried setting env but Next Auth won't pick it up). Would that be enough for one-off cases? This would need to work with Next's build too https://github.com/vercel/next.js/blob/canary/packages/next/build/index.ts

[MarkusWendorf]

@leerob I've seen something along the lines of this: "env-cmd -f .env.staging yarn build" pretty often. Mostly used in CRA projects.

The proposed -e option would be equivalent:
env-cmd -f .env.staging next build would become next build -e .env.staging

I think this post from Stackoverflow describes it quite nicely (https://stackoverflow.com/a/61750672).

Next 9.4 has built-in support for .env files: https://nextjs.org/docs/basic-features/environment-variables

But, in case you want to have multiple .env files, like:

• .env.development
• .env.staging
• .env.prestaging
• .env.production

It would be impossible to do with a built-in env variables support. There's only 3 environments that officially supported for now, it's: "development", "test", "production". With next dev you use "development", next build && next start uses "production" environment.

If you need to build for production environment, but using ".env.staging" for example, then you need to add env-cmd package, and add this line to your package.json:

"build:staging": "env-cmd -f .env.staging yarn build && yarn start"
Next would make a production build with ".env.staging" variables.

[eric-burel]

I am currently upgrading to latest version of everything, and I struggle to load variables in Cypress using Webpack 5. I think this is related to the fact that Webpack 5 no longer polyfills Node related stuffs, which seems to include allowing to use process.env in the frontend.

I am adding this:

plugins: [
    new webpack.DefinePlugin({
      "process.env": JSON.stringify(process.env),
    }),
  ],

But haven't yet found a way to call loadEnvConfig asynchronously (not sure if I can create the webpack config asynchronously) + it relies on side effect so API is not obvious.

No idea why the doc propose an async usage either in the documentation, as this function seems synchronous?

It might be interesting to extend this RFC to "loading for different environments AND tools", because the usage is definitely related to the continuous integration pipeline.

Edit: final code that seems to work (but not really documented) in my Cypres config:

  plugins: [
    new webpack.DefinePlugin({
      // TODO: also load variables from .env.test
      // @see https://github.com/vercel/next.js/discussions/25764
      "process.env": JSON.stringify(loadEnvConfig(process.cwd()).combinedEnv),
    }),
  ],

[xer0x]

👋 I'm using Vercel domains to host the same Nextjs app, and associate it with different back-end APIs using NEXT_PUBLIC_APP_ENV. I'm wondering if anyone else is doing this, and if they can suggest a method of configuring our services using the domain?
Today, we set an environment variable, and I don't see an easy way to make this work with .env either.

[goo32]

I think this RFC is great and provides a flexible solution with minimal change.

That being said, I think ALL front end frameworks need to stop baking in environment specific config into the build. Environment specific config should be resolved at runtime. Here's an interesting project that does exactly that and works with Next.js and CRA .env files. https://github.com/andrewmclagan/react-env

[mattcarlotta]

I'd caution against using that package as it exposes the ENVs to the client window; therefore, it's very easy to change an ENV, navigate to another page, navigate back and see something UI related that shouldn't be visible. While I wouldn't consider this a security vulnerability, there's a reason why ENVs are loaded into process.env and it's because process is not readily accessible to the client.

[eric-burel]

I am not sure exposing ENV is a limitation, any config client-side is exposed to the client and can be altered. I do like the idea of easily switching the env configuration at runtime. It really confuse our devops that the app must be rebuilt on environment variable changes.

[eric-burel]

However isn't it redundant with node-config? Switching env values at runtime seems very similar to using file based JSON configs.

[lucasbasquerotto]

I think runtime configs should be the default. This allows to decouple the build artifacts from the environment.

For example, in our backend (java-based) we generate a docker image with the WAR file generated from the build step and load the environment when the container generated from the docker image runs in the target machine (be it the staging or production one). This is good not only from a devops perspective (only one build is needed, so it's less complex) and from a security perspective (the docker image pushed to the registry doesn't have any environment specific variables), but also avoids problems like "it worked in our staging environment, but not in production", because even if the build step is the same, the packages downloaded in the build step may have changed in the upstream.

In the case of nextjs this can happen too. For example, a npm package changed in upstream, using the same minor version, but for some reason some change in it break your app. In this case, even running the same build step, it could have different results if run before or after the change in the upstream. Not only that, but you would need to run the build step several times, one for each environment, generating different build artifacts to be pulled from different places, which would make the devops more complex (unless you build directly in your production server, which is something I don't do because I prefer the build step to be done in a CI environment).

[pavankjadda]

I think we can take que from Angular build here. By default build the code in production mode and just use environment files to load variables specific to environment (And still provide an option to run on IDE/Locally) . This is so much and easy to understand

    "local": "next local",
    "build:development": " next build --configuration development",
    "build:test": "next build --configuration test",
    "build:production": " next build --configuration production",

[eric-burel]

Yeah but not very clear about the end result. For instance will this alter NODE_ENV? It feels like it adds another layer of abstraction in addition to the traditional "NODE_ENV" concept, I prefer a slightly uglier API that is more explicit to a slightly nicer abstraction that is less explicit.

[lucasbasquerotto]

I don't think this abstraction is misplaced, tough. When I think of NODE_ENV=prod I think mainly about performance, minified code, etc..., while I think of dev, staging, test and prod environments mainly about specifics about the environment, like endpoints and tokens. I may want to run a development environment (in the sense that I will run locally with development endpoints and test tokens) but with the code minified and production-like, so as to have an understanding about how it will be in production.

That said, I'm not against using NODE_ENV to define the environment, as long as it's not coupled with optimizations and the like. For example, export NODE_ENV=dev && next build would use development environment variables, but it would be optimized for production (for development I would use mainly the dev command tough), and it would accept any number of options like staging, test and prod, but I don't know if it would work well because NODE_ENV normally accept only dev and prod, and adding other options could have unintended side-effects, in which case the proposal of @pavankjadda would be the way to go IMO.

Of course, that depends of how NextJS generates the code behind the scenes, but I think that next dev is coupled with NODE_ENV=development and next build (and start) is coupled with NODE_ENV=production. More details at: https://stackoverflow.com/a/69114213/4850646

[rtrembecky]

Spot on. What I'm doing using the react-env package is all the combinations of next dev and next start commands with all the environments defining the endpoints - dev/stg/prod. So I end up having these scripts in package.json:

    "next-dev": "react-env -e ENV -- next dev",
    "dev:dev": "ENV=dev yarn next-dev",
    "dev:stg": "ENV=stg yarn next-dev",
    "dev:prod": "ENV=prod yarn next-dev",
    "next-start": "react-env -e ENV -- next start",
    "start:dev": "ENV=dev yarn next-start",
    "start:stg": "ENV=stg yarn next-start",
    "start:prod": "ENV=prod yarn next-start",

I just write this here to visualize a real use case and how it gets confusing when the word "environment" means different things - imagine telling your colleague to run yarn dev:stg and the expression on their face 😄
If we are to keep NODE_ENV=development/production naming (and actually test as well) together with next dev/build/start commands, I think it should be recommended to name your endpoint environments differently - e.g. local/staging/? - I don't know what to call production... at least prod so it's different 🤔

[zanettin]

@flybayer do you plan to submit a PR for this topic and @leerob would you see a chance to get the PR merged into the core? I'd really love to see this enhancement on the env pkg since also our app deals with >3 envs and i don't get the point why the framework should limit that. thanks for raising this @flybayer and @leerob for your guidance 🙏

short update regarding the RFC specs: guess we should also make the path to the env files configurable. having them all on the project root is a bit cluttered imo

[flybayer]

@zanettin yes we do, likely soon

[zanettin]

@zanettin yes we do, likely soon

if you need a hand, ping me pls! wish you all merry xmas and stay healthy and safe

[krish-penumarty]

+1 really looking forward to this solution.

[EgorZotov]

I faced this problem today. Suggestion for next-config.js from head comment is good but be aware about next.js forceful override.

Don't use .env.production, .env.development names for files and replace them with something like .env.prod and .env.dev so next.js won't pickup them.

This is really bad solution so hoping to see PR for better enviroment managment.

[liho00]

I like the way how vite js using mode concept to load the env variables, have a look guys ~ https://vitejs.dev/guide/env-and-mode.html

[mattpetters]

thanks so much for this workaround --- saved the day

[mpvosseller]

As mentioned by @EgorZotov the proposed workaround by @flybayer won't work if you have .env.development or .env.production files present because Next.js will load one of those first before dotenv-flow loads .env.staging. Also some of the files end up being read / processed twice because both Next.js and dotenv-flow read/process them. My solution was to just store the .env files in a different directory (./config). Here is my implementation: https://gist.github.com/mpvosseller/a448ef380bcbcc7f810e8b79661e2561

[petertflem]

Just going to add my two cents here. Having to use the production environment variables for staging is problematic for me because of:

• I pass the host name as env variable. It will always differ.
• We will likely do testing on staging. If we do this against a production config, end users will be notified in certain scenarios.

[flybayer]

Solution 🔥

With the recent Blitz 2.0 pivot, the blitz CLI is now a small standalone thing you can use to solve env variable loading with next.js.

1. npm i blitz
2. blitz [dev|build|start] -e staging

This is a super thin wrapper over next cli with no perf overhead that:

1. Loads correct .env.X and .env.X.local files based on the -e X flag that you specify.
   • Ex: -e staging loads .env.staging
2. Sets process.env.APP_ENV to the env name.
   • Ex: -e staging => APP_ENV=staging
3. Passes all other args directly to nextjs cli

[matijagrcic]

More at https://blitzjs.com/docs/custom-environments#custom-environments and for export at https://blitzjs.com/docs/cli-export.

Thanks for this, expecting to just use production, development, and test is fine for most apps, but in enterprise orgs you usually have QA, UAT etc.

[saurishkar]

Rather than having multiple files for env by using dotenv I instead hooked it up to a single .yml file and added minor config which is inspired by the CRA config of using env.
If anyone wants to explore: https://stackoverflow.com/a/69619744/6883773

[Keshavdulal]

I am using package.json's script to copy different environment secrets to .env.local based on the command invoked.

"build-dev":"cp .env.dev .env.local && yarn build",
"build-prod":"cp .env.prod .env.local && yarn build"

I won't say its ideal but get the job done in my case.
https://stackoverflow.com/a/76724510/3556531

[IvanKuzyshyn]

I'm doing pretty much the same as @Keshavdulal mentioned but in the Dockerfile when building image for different environments, like:

COPY ./envs/.env.$APP_ENV ./.env.production
RUN pnpm build

[brettstack]

This is the correct answer. Here's what my package.json scripts looks like:

  "scripts": {
    "start-ui:dev": "ENVIRONMENT=development npm run copy-dotenv-dev && next dev -p 3001",
    "start-ui:staging": "ENVIRONMENT=staging npm run copy-dotenv-dev && next dev -p 3001",
    "start-ui:prod": "ENVIRONMENT=production npm run copy-dotenv-dev && next dev -p 3001",
    "copy-dotenv-dev": "cp ./.env/.env.$ENVIRONMENT ./.env.development ; cp ./.env/.env.$ENVIRONMENT.local ./.env.development.local ; :",
    "copy-dotenv-build": "cp ./.env/.env.$ENVIRONMENT ./.env.development ; cp ./.env/.env.$ENVIRONMENT.local ./.env.development.local ; :",
    "start-ui-local-api:dev": "NEXT_PUBLIC_ApiEndpoint=http://localhost:4911 npm run start-ui:dev",
    "start-ui-local-api:staging": "NEXT_PUBLIC_ApiEndpoint=http://localhost:4911 npm run start-ui:staging",
    "start-ui-local-api:prod": "NEXT_PUBLIC_ApiEndpoint=http://localhost:4911 npm run start-ui:prod",
    "build-only:dev": "ENVIRONMENT=development npm run copy-dotenv-build && next build",
    "build-only:staging": "ENVIRONMENT=staging npm run copy-dotenv-build && next build",
    "build-only:prod": "ENVIRONMENT=production npm run copy-dotenv-build && next build",
    "build:development": "ENVIRONMENT=development npm run copy-dotenv-build && next build && next export",
    "build:staging": "ENVIRONMENT=staging npm run copy-dotenv-build && next build && next export",
    "build:production": "ENVIRONMENT=production npm run copy-dotenv-build && next build && next export"
}

And I add this to .gitignore

.env.local
.env.*.local
/.env
/.env.*