Not possible to use different configurations in staging + production??

[JVMartin]

Evidently, it's not possible to use different configurations in staging + production.

We have a NextJS application packaged up in Docker, so that it's environment agnostic. Therefore, we need to supply different configurations for staging and production environments, of course. For instance, our staging Next front-end should hit a different back-end API_URL than our production Next front-end.

Per the documentation, we should be able to do runtime configuration like this in our next.config.js:

serverRuntimeConfig: {
  apiUrl: process.env.API_URL,
},

If this were true, we would be all set!

But the documentation is definitely wrong, because per the documentation elsewhere:

So since process.env.* is always interpolated at build time into the compiled assets, it appears to not be possible to use different configurations in different environments, totally defeating the purpose of environment variables.

This totally violates all principles of "build once, deploy anywhere", "immutable deployments", "test the artifact before promoting to production", etc.

Does Next deliberately violate these principles or is this an accident? Any ideas of any hacks or workarounds to let me run a Next application in multiple environments - without multiple build artifacts, because it is obviously critical that the artifact being promoted into production be identical to the one in test / staging environments?

Relevant issues, all totally unresolved:
#1488
#15131
https://stackoverflow.com/questions/60364413/react-next-js-recommended-way-to-set-constants-such-as-backend-api-urls
https://stackoverflow.com/questions/60871862/nextjs-prevent-env-vars-to-be-required-on-build-time
#17641

[leerob]

Is there any reason not to use Environment Variables for this?

[dlindenkreuz]

@leerob I‘d love to read a follow-up on this topic – could you give this another look? 👀

[pkit]

It doesn't work with env variables too. Mainly because all env vars are "cached" in .next/required-server-files.json (wtf is that?)
So subsequent next builds with different env vars still produce the same result.
Need to delete .next dir between builds. Who thought that it's a good idea?

[CleberRossi]

@JVMartin and @pkit I'm facing the same issue.
However, reading the documentation I think it is possible to use, some worthy mention points.
You cannot use PUBLIC env because NEXT will replace it. (Need to use next.config.js)
You cannot use static generation.

Other thing is that I tested my .next folder to check if process.env were being changed, it seems NOT. It only happened for PUBLIC variables. So you can do it, but you cannot use static generation again.

I will be creating a docker file and try to use this approach to check. Some other posts to help you out:
#22266
https://blog.vulcanjs.org/how-to-set-configuration-variables-in-next-js-a81505e43dad
https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser

Conclusion for now: If you are using server side rendering it is possible to use process.env

[pkit]

I don't see any clear steps or explanation here.
I don't care about SSR.
I do care that env vars I use, will be used at build time. That's it.

[dtinth]

Maybe if we step back - your original problem is you want to use different configurations for staging + production. What's the use case for reading values at runtime for different configurations instead of at build time to differentiate environments?

@leerob Consider a case where a web-based application is packaged and distributed as a Docker image (e.g. for on-premises installation). Popular open source examples include n8n, pgAdmin, Redis Commander, and Mongo Express. These applications all allow users to configure the behavior of the app via environment variables, without having to rebuild an image.

For this kind of app, we want to let users easily run it by just doing docker run --env-file=.env <image>

It is unreasonable to ask the user to download the source code and build the Docker image by themselves each time they want to change the configuration. First, it is extremely inconvenient. And second, in SaaS companies that offer on-premises installation, we want to ship the compiled package to clients and want to keep the source code private.

Recent features in Next.js has worsened the situation. Output File Tracing and App Directory has broken the Runtime Configuration feature with no documented alternative. Right now I’m using these workarounds, but it’d be great if Next.js offers a first-class solution for this, or at least, document in the Docker deployment docs on how to allow a single build artifact to be reused in multiple environments.

[michrome]

Hey @JVMartin serverRuntimeConfig does read from the environment as per the runtime configuration documentation. Try the following:

1. Add the following to next.config.js.

serverRuntimeConfig: {
  mySecret: process.env.MY_SECRET,
}

2. Create a new page.

import getConfig from "next/config";
const { serverRuntimeConfig } = getConfig();

function Page({ secret }) {
  return <div>My secret: {secret}</div>;
}

Page.getInitialProps = async (ctx) => {
  const secret = serverRuntimeConfig.mySecret;
  return { secret: secret };
};

export default Page;

3. Create a .env file.

MY_SECRET=foobar

4. Run npx next build. Note: you will see {"mySecret":"foobar"} included in required-server-files.json.

5. Run npx next start and view your page in a browser.

6. Stop the server, update .env with a new value, re-run npx next start (don't rebuild!) and refresh the browser.

MY_SECRET=new value

7. Stop the server, delete the .env file, run MY_SECRET="another value" npx next start (again, don't rebuild) and refresh the browser.

[brycefranzen]

For what it is worth. I work at the same organization as @JVMartin and we ultimately ended up using the next.js runtime configuration documentation to solve our issue.

The way the site builds is still odd though-- it builds with whatever env params are provided at build-time (they're hard-coded in the build output); however, when using the "runtime config" helpers, it magically works and disregards the env params in the build output and uses the params passed in.

Basically, do what @michrome said, and it'll work just fine.

[michrome]

Basically, do what @michrome said, and it'll work just fine.

If only my kids would sign up to this thinking…

[geekcubed]

Has there been any new information on this? We're faced with the exact same issue.

Our NextJS product is built and baked into a Docker image. This is then ready to be distributed to our customers to install on their own infrastructure, often inside their network firewall. Our app requires a bunch of stuff to be configured during / after deployment: Graph API connection strings, Azure Active Directory configuration etc. Which means we're facing the same challenges: configuration stored in either .env files or .next.config.js is baked into the compiled code during build, even if we're using process.env.*.

Specifically for us, a lot of this configuration code is consumed "outside" of a page - e.g. in a hook or library object, I'm not even sure we can we even apply the getInitalProps hack (and that's what it is)? Right now it seems to be less work to dump NextJS and go back to vanilla React backed by a more production-ready backend

[AgentChris]

Hey, @geekcubed @JVMartin we faced a similar issue (for configuring sentry environment property)
What we did was to create a config endpoint and this is how we solved it. I know is not ideal but at least we respect the "build once, deploy anywhere"

.env

NEXT_PUBLIC_ENVIRONMENT=DEVELOP

next.config

...
  publicRuntimeConfig: {
    environment: process.env.NEXT_PUBLIC_ENVIRONMENT,
  },
  ...

pages/config.ts

import { NextApiRequest, NextApiResponse } from 'next';
import getConfig from 'next/config';

export default async function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
  res.status(200).json(getConfig());
}

sentry.client.config

import { NextConfig } from 'next';
import * as Sentry from '@sentry/nextjs';
import axios, { AxiosResponse } from 'axios';

const SENTRY_DSN = process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN;

axios.get('/api/config').then((response: AxiosResponse<NextConfig>) => {
  const { publicRuntimeConfig } = response.data;
  Sentry.init({
    dsn: SENTRY_DSN,
    // Adjust this value in production, or use tracesSampler for greater control
    tracesSampleRate: 1.0,
    environment: publicRuntimeConfig?.environment,
  });
});

sentry.server.config

import * as Sentry from '@sentry/nextjs';
import getConfig from 'next/config';

const SENTRY_DSN = process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN;

const { publicRuntimeConfig } = getConfig();
Sentry.init({
  dsn: SENTRY_DSN,
  // Adjust this value in production, or use tracesSampler for greater control
  tracesSampleRate: 1.0,
  environment: publicRuntimeConfig.environment,
});

[geekcubed]

[We]'ve ended up just using the process.env props and really restricted where we consume the settings and trusting that it works. For now, we've gotten away with it, but it's far from ideal and I don't know enough about what's happening under the hood to appreciate what we've compromised by doing it this way.

With background in php and .net, I'm struggling to see the benefits that next brings to the party in terms of server-side rendering

[stigkj]

I'm not sure about the reason for having the env.vars. getting built in like Next.js is doing, but there is at least an easy way around it: use another library for reading config, like node-config.

[dlindenkreuz]

@AgentChris You should probably not serve the config object as-is. It might contain secrets meant only for the server.

export default async function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
  const { publicRuntimeConfig } = getConfig(); // ← 👀 
  res.status(200).json(publicRuntimeConfig);
}

[mnebuerquo]

The root problem is that when you build the content statically, you have to choose what content to build. If you have staging content and production content, you can't "build once, deploy anywhere" with static page generation at build time. You either build with staging content or you build with production content. This is true regardless of how you package your build artifacts. You can use docker or tar files or anything, but static content in the image makes it environment specific.

The choice seems to me as either of the following:

1. Build separate stage and production images with everything built statically in the image, or
2. Build an environment agnostic image which can generate static content at startup.

The "build once, deploy anywhere" philosophy is at odds with having statically generated pages and content built into the image. There isn't a way to do both, regardless of how you import your configuration.

This isn't a question of "doing it wrong" or not following best practices. The decisions made by the Next team are optimized for the specific feature of generating static content at build-time and keeping secret configuration from landing in the browser in the process. If you want "build once, deploy anywhere" as the priority, then you would make different decisions in the platform architecture. There wouldn't be a build-time option, instead opting to build on-demand or at server startup.

[JVMartin]

Everyone at my organization is running Next as an express server, doing server-side rendering, taking data and transforming it to pages server-side in real-time. We are not using it as a static site builder, we would use a more appropriate tool like Gatsby for that. So, Next definitely should, in our use case, conform to every aspect of a 12-factor app, and should definitely follow the build once, deploy anywhere philosophy.

[hongymagic]

Unironically, this is the way the commercials are for Vercel. More builds = more workers = $50USD/month (per extra worker). Also serves the "serverless" I-charge-you-per-API-hit ecosystem very well.

I guess in this paradigm, no one cares that code mutates between environment to environment....

[AnthonyDugarte]

As of now, you don't need to build all of your site on build time, and you can make usage of static generation across environments, with a single build, by making usage of ISR, I think it is a nice feature that allows you to fix this particular issue.

[tjcampbell]

@AnthonyDugarte that unfortunately isn't true. Anything statically generated at build time will include injected runtime config that was specified at build time. For dynamic routes you can defer static generation, but not for other pages that depend on runtime config. So the initial page load for every environment will be the same, until cache invalidation where pages are regenerated with the the new runtime config.

[volodymyr-strilets-mindcurv]

Check this lib for the client-side environments
https://github.com/andrewmclagan/react-env#readme

[dtinth]

The Runtime Configuration feature is now considered “legacy” and do not work with Output File Tracing (they gets inlined during build) or React Server Components (crashes the dev server).

I’ve written a note about this topic: Runtime Environment Variables in Next.js

What I currently do right now:

• In server-side code (API routes and getServerSideProps) I use global.process.env instead of process.env.
• In client-side-only components I just do client-side fetching using React Query (via tRPC) to fetch public variables from an API route that exposes the public variables.

[fireai-developer]

Thanks @dtinth for spelling it out so clearly. I ended up at the same approach for client-side-only components as you, so glad to see I was not the only one thinking in that direction. 👍

[lucasbasquerotto]

I think that a client-side request to fetch the variables is a no go if you need SSR/SSG, and the variables need to be set beforehand. It could be possible fetching in the server side, before anything else, although I hadn't tried yet.

[dangduytung]

To solve for the problem about multiple environments in building Docker of the application NextJs, I wrote the answer here:
https://stackoverflow.com/questions/77329575/different-env-variables-for-the-same-nextjs-docker-image/78112804#78112804

[aliaz0]

How can I modify the contents of the next.config.js file itself to handle two different environments? I need to set different hosts for images.remotePatterns based on the environment. Is it possible to build a single Docker image and use it across multiple environments, each with a different Next.js configuration?
To clarify, I’m not referring to runtime variables used in the application (which I already manage with the next-runtime-env package) but specifically to changing the Next.js configuration at runtime, in any way possible.

[lucasbasquerotto]

I'm not using remotePatterns, but I'm using environment variables in other parts of the config file. It should be possible using process.env.VAR_NAME:

images: {
    remotePatterns: process.env.REMOTE_PATTERNS
}

Then, you just need to specify REMOTE_PATTERNS as the docker container environment variable.

[aliaz0]

@lucasbasquerotto Are you sure about this? If I use process.env.VAR in my Next.js configuration, the build process fails with the error: "images.remotePatterns[0].hostname" is missing. If I provide these environment variables on the machine where the Docker image is built, they get resolved to their values at build time and cannot be changed at runtime. Am I misunderstanding something?

[lucasbasquerotto]

@aliaz0 Make sure to follow the structure required for remotePatterns. For example, in this case it might need to be:

images: {
    remotePatterns: [ hostname: process.env.REMOTE_PATTERN_HOSTNAME ]
}

and possibly other fields that may be required.

About the second part of your comment, NextJS should use the current environment variables that are defined in the config file when running the container, like it happens with the variables in the field publicRuntimeConfig, but it might be that places that you define them may use them only during build and they end up "hardcoded" in the generated build artifacts.

Building in a container with environment variable MY_VAR: "A" and running in a container with MY_VAR: "B" should populate the config file with MY_VAR: "B" when running NextJS, but if the variable is defined in a setting that is used only during build, only the build setting will be used, unfortunately. I don't know if this is the case of remotePatterns (running a test of this case should be able to provide the answer).

[tappin-kr]

Would be nice to get an answer/guidance for this question.