Allow dynamic serverRuntimeConfig and publicRuntimeConfig values from process.env.* with outputStandalone: true

[varbrad]

Describe the feature you'd like to request

Currently, using

experimental: {
  outputStandalone: true
}

in a next.config.json will produce a server.js file that will encode the environment variables into the bundle at build-time.

Currently our next.config.js looks like this;

module.exports = {
  serverRuntimeConfig: {
    someSecret: process.env.SOME_SECRET,
  },
  publicRuntimeConfig: {
    someValue: process.env.SOME_VALUE,
  }
}

and once we have done a next build with the standalone experimental bundler, we end up with server.js looking something like;

// ...
"serverRuntimeConfig": { someSecret: 'test' },
"publicRuntimeConfig": { someValue: '' },
// ...

Where it has resolved the process.env.* at build-time.

This - although it works - is less than desirable for our use case as we like having control of these variables at runtime when running our Docker image in k8s.

Describe the solution you'd like

Ideally a way to tell Next.js to not encode/bundle these values at build time, and instead leave them unchanged.

Ideally, I want the server.js to remain as;

// ...
"serverRuntimeConfig": { someSecret: process.env.SOME_SECRET },
"publicRuntimeConfig": { someValue: process.env.SOME_VALUE },
// ...

As this then allows us to inject these process.env.* values at runtime, having more control over the application.

Describe alternatives you've considered

Currently I've experimented with automatically re-writing the server.js file once it gets built, and replacing with our pre-defined serverRuntime & publicRuntime config objects. This works perfectly - and is currently running perfectly well in our experimental k8s cluster/deployment pipeline :)

[michaelschufi]

I second this. Having some way to opt-out of the build-time environment variable enforcement would be very helpful. I do not want to create multiple artifacts (i.e. images) just because a few variables are different on different environments.

Thank you for describing your current workaround. I was not even aware, that outputStandalone exists! Have you found some docs for this feature?

Edit: Some info about the new feature can be found here Self-hosted Next.js improvements.

[varbrad]

Hi there folks,

Is there any potential discussion/thoughts around this? We've currently got an experimental release of our application working with the server-rewrite trick (We actually replace it with our own custom server.js with some other goodies) but would love this to be supported out-of-the-box. If I get some time I may be able to raise a PR showing a PoC? 👍🏻

For our production app, the current Docker image is pushing the 900Mb mark (Which is a bit of a beast - and we've got quite a lot of optimization to reduce that already!) whereas the condensed bundle through the standalone deployment just barely clocks in at over 140Mb with no additional optimization - which is a fair bit smaller!

Thanks all, have a lovely day 😃

[romeovs]

I'm running into similar issues.

I would like to turn on outputStandalone for my builds and get tiny docker images, but this issue is preventing me from doing so unfortunately.

Since the next.config.(js|mjs) file seems to be copied into .next/standalone by the build, could we read the publicRuntimeConfig and serverRuntimeConfig from there instead?

That way, any logic used in next.config.(js|mjs) is preserved and there are no breaking changes.

[AAllport]

It's a bit frustrating that this caveat does not seem to be mentioned in the docs at all.

What started as a simple quest to add a maintenance mode flag to our project is turning into a refactor of the docker file, and not in a way that's desired.
Please can reading from process.env for the runtime config to be supported with standalone mode

[trevorr]

It's a bit frustrating that this caveat does not seem to be mentioned in the docs at all.

+1000

[kieranbenton]

Same - its a pretty big hole to fall in and you don't really find out about it until you've done a lot of other work!

[Fluder-Paradyne]

same I was done with all the optimizations and when we pushed docker image
found that users can't set their own values

[marc0olo]

💯

[mateodelnorte]

Does anyone have a suggested workaround here? envsubst or sed in the CMD of the Dockefile?

All examples I see of providing env vars to a next.js site tend to mention using config files, which just doesn't work in a kubernetes based environment. We have twelve-factor apps that rely on environment variables.

[Zwooosh]

I know it's not a real solution, but since server.js is using process.env.PORT, I figured why not replace the hardcoded values with the original next.config.js env variables?

I made a rather crude script that replaces the publicRuntimeConfig inside server.js that runs immediately after build and that did the trick.

Until there is a better solution, maybe this will be of help to anyone:

const fs = require('fs/promises');
const prettier = require('prettier');

const SERVER_FILE_PATH = '.next/standalone/server.js';

(async function () {
  try {
    console.log('Replacing publicRuntimeConfig with env variables...');

    // Get next config
    const config = await fs.readFile('next.config.js', { encoding: 'utf8' });
    // Extract publicRuntimeConfig
    const publicRuntimeConfig = config.match(/publicRuntimeConfig[^{]*?(?:{\s+[^}]*?})/gm)[0];

    // Get standalone server.js file
    const server = await fs.readFile(SERVER_FILE_PATH, { encoding: 'utf8' });

    // Replace hardcoded publicRuntimeConfig
    const newServer = server.replace(
      /("publicRuntimeConfig":[^{]*?(?:{[^}]*?}))/gm,
      publicRuntimeConfig
    );

    // Format output string
    let formattedServer;
    await prettier.resolveConfig('.prettierrc').then(options => {
      formattedServer = prettier.format(newServer, { parser: 'babel', ...options });
    });

    // Write to file
    await fs.writeFile(SERVER_FILE_PATH, formattedServer, 'utf8', function (err) {
      if (err) return console.log(err);
    });

    console.log('Done!');
  } catch (err) {
    console.log(err);
  }
})();

[mlarcher]

FWIW here's how we dealt with it iterating on @Zwooosh code sample:

// runtimeConfig.js

exports.getRuntimeConfig = () => {
  const serverOnlyConfigEnvVariables = [];
  const commonConfigEnvVariables = ['API_BASE_URL', 'JWT_PREFIX', 'TOP_DOMAIN', 'DEBUG'];

  const getMappingFromEnv = (names) => {
    return names.reduce((acc, name) => {
      if (name in process.env) {
        acc[name] = process.env[name];
      }
      return acc;
    }, {});
  };
  const serverRuntimeConfig = getMappingFromEnv(serverOnlyConfigEnvVariables);
  const publicRuntimeConfig = getMappingFromEnv(commonConfigEnvVariables);
  return {
    serverRuntimeConfig,
    publicRuntimeConfig,
  };
};

// next.config.js

const { getRuntimeConfig } = require('./runtimeConfig');

const { serverRuntimeConfig, publicRuntimeConfig } = getRuntimeConfig();

module.exports = {
  // apply NextJS image optimization to images from those domains
  images: {
    domains: ['storage.googleapis.com'],
  },
  // Will only be available on the server side
  serverRuntimeConfig,
  // Will be available on both server and client
  publicRuntimeConfig,
  // required for K8s deploy
  // cf https://github.com/vercel/next.js/tree/canary/examples/with-docker#using-docker
  experimental: {
    outputStandalone: true,
  },
};

// injectConfig.js:

#!/usr/bin/env node
const fs = require('fs/promises');
// in production build, dotenv is installed in `standalone` folder via the Dockerfile
const dotenv = require('dotenv');
const { getRuntimeConfig } = require('./runtimeConfig');

dotenv.config();
const SERVER_FILE_PATH = './server.js';

const { serverRuntimeConfig, publicRuntimeConfig } = getRuntimeConfig();

(async function () {
  try {
    // eslint-disable-next-line no-console
    console.log('Replacing publicRuntimeConfig with env variables...');

    // Get standalone server.js file
    const serverContent = await fs.readFile(SERVER_FILE_PATH, { encoding: 'utf8' });

    // Replace hardcoded runtimeConfig
    const publicRegexp = /"publicRuntimeConfig":([^{]*?(?:{[^}]*?}))/ms;
    const serverRegexp = /"serverRuntimeConfig":([^{]*?(?:{[^}]*?}))/ms;

    const publicMatches = serverContent.match(publicRegexp);
    const oldPublicRuntimeConfig = JSON.parse(publicMatches[1]);
    const newPublicRuntimeConfig = {
      ...oldPublicRuntimeConfig,
      ...publicRuntimeConfig,
    };

    const serverMatches = serverContent.match(serverRegexp);
    const oldServerRuntimeConfig = JSON.parse(serverMatches[1]);
    const newServerRuntimeConfig = {
      ...oldServerRuntimeConfig,
      ...serverRuntimeConfig,
    };

    const newServer = serverContent
      .replace(publicRegexp, `"publicRuntimeConfig":${JSON.stringify(newPublicRuntimeConfig)}`)
      .replace(serverRegexp, `"serverRuntimeConfig":${JSON.stringify(newServerRuntimeConfig)}`);

    // Write to file
    await fs.writeFile(SERVER_FILE_PATH, newServer, 'utf8', function (err) {
      // eslint-disable-next-line no-console
      if (err) return console.log(err);
    });

    // eslint-disable-next-line no-console
    console.log('Done!');
  } catch (err) {
    // eslint-disable-next-line no-console
    console.log(err);
  }
})();

// entrypooint.sh

#!/bin/sh

./injectConfig.js

# Hand off to the CMD
# cf https://stackoverflow.com/questions/42857897/execute-a-script-before-cmd
exec "$@"

// Dockerfile:

# Install dependencies only when needed
FROM node:18.2.0-alpine AS deps

WORKDIR /app

# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat

COPY client/package.json .
# we use npm install and not npm ci because package-lock.json is generated on mac host machine and not compatible
RUN npm install

# Rebuild the source code only when needed
FROM node:18.2.0-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY client .

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
# ENV NEXT_TELEMETRY_DISABLED 1
RUN npm run build

# install dotenv for injectConfig script
RUN cd ./.next/standalone && npm i dotenv

# Production image, copy all the files and run next
FROM node:18.2.0-alpine AS runner
WORKDIR /app

RUN apk add --no-cache dumb-init

ENV NODE_ENV production
# Uncomment the following line in case you want to disable telemetry during runtime.
# ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# You only need to copy next.config.js if you are NOT using the default configuration
COPY --from=builder /app/next.config.js ./
COPY --from=builder /app/public ./public
COPY --from=builder /app/package.json ./
COPY --from=builder --chown=nextjs:nodejs /app/injectConfig.js ./injectConfig.js
COPY --from=builder --chown=nextjs:nodejs /app/entrypoint.sh ./entrypoint.sh
COPY --from=builder --chown=nextjs:nodejs /app/runtimeConfig.js ./runtimeConfig.js

# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000

ENTRYPOINT ["./entrypoint.sh"]
# use `dumb-init`, not `npm start` to make sure signals are passed properly and node don't run as pid 1
# cf https://snyk.io/blog/10-best-practices-to-containerize-nodejs-web-applications-with-docker/
# NOTE: this value will be overriden in Kubernetes, to set maxOldSpace value dynamically
CMD ["dumb-init", "node", "server.js"]

This is very rough and not battle tested at all, but hopefully it can make you go further quicker if you face the same issue.

[logikaljay]

@mlarcher This link is broken now, do you have an updated link?

[mlarcher]

It should be #17641 (reply in thread)

[mlarcher]

hum... it seems the link is broken again even though I pasted a working link! The script used by github to set the link text overview is replacing the real link with a broken one...
here it comes as text :https://github.com/vercel/next.js/discussions/17641#discussioncomment-2915095

[logikaljay]

💯 glad I am not the only one who publishes bugs to prod.

[fieldju]

A better approach is available at #17641 (reply in thread)

@mlarcher, why do you assert that the linked approach is better?
It's different and possibly more complicated but not immediately clear to me what makes it's better.

[durdo]

What is the official stand on this feature? Is there a plan to support the use of runtime environment variables (also visible to the client) in the future?

The standalone output is such a cool feature, it is a shame that today we have to choose either it or using runtime environment variables.

[explodingcamera]

As a simpler work-around, I'm just editing the server.js file:

ENV DOCKER 1
RUN sed -i -e 's/"REPLACE_ME_API_BASE"/process.env.API_BASE/' server.js

publicRuntimeConfig: {
  apiBase:
    process.env.API_BASE || process.env.DOCKER ? 'REPLACE_ME_API_BASE' : 'http://localhost:8000',
},

[mauron85]

I think this should be not complicated fix, I will take a look.

The server.js file is created here as long literal:

next.js/packages/next/build/utils.ts

Line 1411 in 4cd8b23

conf: ${JSON.stringify({

Before that config is loaded here:

next.js/packages/next/build/index.ts

Line 264 in 6fd2a7f

const config: NextConfigComplete = await nextBuildSpan

[kachar]

@mauron85 Do you have an update on this? Few months later the standalone mode still lacks runtime configuration.

[Fluder-Paradyne]

@mauron85 any updates on this

[vikingair]

Why did no one make the required modifications also to the .next/required-server-files.json?

I've also the issue that I've got a dynamic assetPrefix configured using different CDN addresses depending on dynamically injected cluster environment variables. This seems to require additional adjustments. Currently, I'm also just coding around all these issues, but any of the above solutions and my own seem pretty fragile.

[dmytrolesyk]

which solution did you end up adopting for dynamic assetPrefix? I''m struggling with this one right now

[afonsomatos]

Not sure why publicRuntimeConfig is considered legacy/deprecated in the docs.
What is the alternative?

[ianldgs]

@fdc-viktor-luft there's a pretty clear message at the top of the page you linked:

Note: This feature is considered legacy and does not work with Automatic Static Optimization, Output File Tracing, or React Server Components. Please use environment variables instead in order to avoid initialization overhead.

That answers @afonsomatos's question as well: use environment variables.
When I need some in the cliend-side, I pass them from getServerSideProps. Otherwise, they need to be defined at build time.

[tballast]

It's not really an alternative though...even directly on the environment variables page it states:

Note: In order to keep server-only secrets safe, environment variables are evaluated at build time, so only environment variables actually used will be included. This means that process.env is not a standard JavaScript object, so you’re not able to use object destructuring. Environment variables must be referenced as e.g. process.env.PUBLISHABLE_KEY, not const { PUBLISHABLE_KEY } = process.env.

So it's still not useful for runtime configuration.

[ianldgs]

Agreed it's not super nice for runtime configuration if you need them on react components:

When I need some in the cliend-side, I pass them from getServerSideProps. Otherwise, they need to be defined at build time.

But to use on getServerSideProps or on api routes, it works fine.

[nictownsend]

But to use on getServerSideProps or on api routes, it works fine.

Are you stating that if you reference process.env.XYZ in getServerSideProps it is evaluated at runtime?

[ianldgs]

But to use on getServerSideProps or on api routes, it works fine.

Are you stating that if you reference process.env.XYZ in getServerSideProps it is evaluated at runtime?

In my experience, yes. Also in /pages/api. Also in Server Components (app dir) 🙃

[tballast]

Editing the server file seems to somewhat work, however I am getting a discrepancy between the server code and the client code when I run my app from a docker container.

If I build using for example NEXT_PUBLIC_API=api.staging.examle.com, and then try to run it in my docker container using NEXE_PUBLIC_API=api.example.com, then it sees the staging endpoint on the client, and the prod endpoint on the server, even though I am pulling the value from the runtime config. Has anyone else experienced something similar?

[logikaljay]

That would be because the value for NEXT_PUBLIC_API is replaced with "api.staging.example.com" at build time.

[alexnthnz]

Do we have any updates or alternatives since this option is considered legacy/deprecated?

[thisismydesign]

FYI you can use Runtime Config as a workaround which is evaluated at runtime.

[francoisjacques]

@thisismydesign I think the OP wants to using standalone mode and runtime config doesn't work in that case.

[shohei-ihaya]

any updates on this?

[florianwar]

I wasted some time on this as well. Sometimes it baffles me how long issues with interest get ignored... My workaround was to add the .env files to .dockerignore and create a custom docker-entrypoint.sh

#!/bin/sh
printenv > /app/.env.production
exec "$@"

and modifying the Dockerfile to use the entrypoint like so

ENTRYPOINT [ "/app/docker-entrypoint.sh" ]
CMD ["node", "server.js"]

[guillaumek]

my 2 cents hack in dockerfile.

RUN sed -i 's/"publicRuntimeConfig":{"processEnv":{}}/"publicRuntimeConfig": { "processEnv": Object.fromEntries(Object.entries(process.env).filter(([key]) => key.startsWith("NEXT_PUBLIC_"))) }/' /app/server.js

[orgads]

Thank you!

Just a small correction, the pattern should be "processEnv":{[^}]*}} (at least in my project, where we have some entries there).

[leerob]

Hey everyone – we have just published new documentation on self-hosting, including how to configure a custom cache handler for use with ISR / Data Cache in both the Pages and App Router. These docs go in depth about how other features like Image Optimization, Middleware, Environment Variables, Build Caching, and more work when self-hosted. There's also updated Docker based examples.

Specific to this discussion, we have provided guidance on how to use runtime environment variables.

https://nextjs.org/docs/app/building-your-application/deploying

[Starefossen]

Tl;Dr; Next.js no longer recommends using the runtimeConfig option, as this does not work with the standalone output mode. Instead, Next.js recommends incrementally adopting the App Router and using process.env.MY_VARIABLE directly.

[leerob]

And depending on your pattern, retrieving the value in getServerSideProps and forwarding to your component might work. It depends if it's a secret value, as the output of getServerSideProps is serialized and sent to the component. Versus with the App Router, since it's a Server Component, the rendering can remain entirely on the server.

[leerob]

Swinging back here, demo repo: https://github.com/leerob/next-self-host

[banool]

It would be amazing if you could manipulate assetPrefix using runtime variables when using standalone output. As it is now, if I have 4 deployments, I have to build four images just so that that one config value in next.config.js is different for each deployment.

[PauMateu]

Any updates on the assetPrefix issue? We are having the same issue about having different images just for one config value in next.config.js... @banool

[filBraga]

Any updates on the assetPrefix issue? Im using the APP Router layout.

Actually, i just removed my doman name and kept the path. It worked!

Example:

- assetPrefix: 'https://prod.mydomain.com/my-custom-path'
+ assetPrefix: '/my-custom-path'