Runtime environment variable for baseUrl for both server and client in Next.js

[nemanjam]

As stated in docs:

https://heyapi.dev/openapi-ts/clients/next-js#runtime-api

for @hey-api/client-next recommended way to configure client is to set path to external file runtimeConfigPath: './src/hey-api.ts', this is my file:

https://github.com/nemanjam/full-stack-fastapi-template-nextjs/blob/main/frontend/apps/web/src/lib/hey-api.ts

// frontend/apps/web/src/lib/hey-api.ts

import { isServer } from '@/utils/runtime';
import { PROCESS_ENV } from '@/config/process-env';

// import { waitMs } from '@/utils/wait';

import type { CreateClientConfig } from '@/client/client.gen';

const { NEXT_PUBLIC_API_URL } = PROCESS_ENV;

/** Runtime config. Runs and imported both on server and in browser. */
export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl: NEXT_PUBLIC_API_URL,
  credentials: 'include',
  ...(isServer() ? { fetch: serverFetch } : {}),
});

const serverFetch: typeof fetch = async (input, init = {}) => {
  // Note: Dynamic import to avoid bundling 'next/headers' on client
  const { cookies } = await import('next/headers');

  const cookieStore = await cookies();
  const cookieHeader = cookieStore
    .getAll()
    .map((c) => `${c.name}=${c.value}`)
    .join('; ');

  // Note: must append auth_cookie like this or content-type header will break in server actions
  const headers = new Headers(init.headers);
  headers.append('Cookie', cookieHeader);

  // test skeletons styling
  // await waitMs(3000);

  const response = fetch(input, { ...init, headers });

  return response;
};

Here I have custom fetch function serverFetch to forward cookies. That is mostly irrelevant for this topic, but it's one example how to have async code in configuration, which is relevant for this thread. I see that export const createClientConfig: CreateClientConfig = (config) => ({...}) cannot be async.

Main idea:

I want to have reusable Docker image with runtime environment variables. Having dynamic baseUrl: NEXT_PUBLIC_API_URL applied on both server and client @hey-api/client-next is part of that requirement.

For runtime environment variables i would have to read them in import 'server-only' file, that will fork for server client but is unavailable for client that runs in browser.

import 'server-only';

import { processEnvSchema } from '@/schemas/config';
import { validateData } from '@/utils/validation';

import { ProcessEnvType } from '@/types/config';

// Note: maybe function for runtime vars
const processEnvData: ProcessEnvType = {
  NODE_ENV: process.env.NODE_ENV,
  NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL,
  NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
};

export const PROCESS_ENV = validateData(processEnvData, processEnvSchema);

For browser i would need to inject window.__ENV in some script tag in server component and use that to set baseUrl for client. Or make API endpoint and fetch env, but it would make it async. createClientConfig() isnt async to set async baseUrl, but fetch override is async function, I could set baseUrl via the first argument in fetch(input, { ...init, headers }).

These are all options and possible directions, more or less hacky, but is there already standard way to accomplish main goal? To set baseUrl at runtime for both server and client in a frontend/apps/web/src/lib/hey-api.ts file. I would want to avoid passing custom client instance for each specific call, or use client.setConfig() since runtimeConfigPathis already stated as proffered method, and I already use it for cookies.

[ther12k]

Short version: createClientConfig can't be made async by design, so the standard pattern is to resolve baseUrl synchronously from whichever source is available per environment (server process.env vs. a runtime-injected window.__ENV), rather than making the config function async.

The constraint you've hit is actually Next.js's, not hey-api's. Anything the browser needs must be inlined into the client bundle, and NEXT_PUBLIC_* vars are inlined at build time, not read at runtime in the browser. So reading process.env.NEXT_PUBLIC_API_URL in hey-api.ts gives you build-time inlining on the client — which fights the "one reusable image" goal.

There are two clean ways to get true runtime baseUrl under the runtimeConfigPath pattern:

Option A — Inject window.__ENV and read it in config (recommended for your case)

You already sketched this; it's the idiomatic Next.js solution and it's not as hacky as it looks.

1. In a server component layout, serialize the runtime env into a script tag before your app boots:

// app/layout.tsx (server component)
export default async function RootLayout({ children }) {
  const apiHost = process.env.API_HOST; // server-side, runtime
  const envScript = `window.__ENV = ${JSON.stringify({ API_URL: apiHost })};`;
  return (
    <html>
      <head>
        <script dangerouslySetInnerHTML={{ __html: envScript }} />
      </head>
      <body>{children}</body>
    </html>
  );
}

2. In hey-api.ts, resolve baseUrl synchronously by reading whichever source is available:

const baseUrl =
  typeof window !== 'undefined'
    ? window.__ENV?.API_URL          // browser: runtime-injected
    : process.env.API_HOST;          // server: runtime env var

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl,
  credentials: 'include',
  ...(isServer() ? { fetch: serverFetch } : {}),
});

This keeps createClientConfig sync (as required), works with the same Docker image across environments, and doesn't need client.setConfig() or per-call client passing.

Option B — Build-time per-image bake (if you don't need one image for many envs)

If "reusable image" just means "build once, run anywhere in CI", set NEXT_PUBLIC_API_URL as a build-arg:

ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
RUN npm run build

Then your existing PROCESS_ENV.NEXT_PUBLIC_API_URL config works as-is. Not truly runtime, but zero client-side plumbing.

Why you can't just make createClientConfig async

runtimeConfigPath imports and invokes it synchronously when the client module loads; making it async would return a Promise as the config object, which the client won't await. The fetch override stays async because it runs per-request, not at config time — that's why your cookie-forwarding works there but an async baseUrl wouldn't. So the answer is to resolve baseUrl synchronously (Option A's window.__ENV lookup), not to make the whole config async.

Which to pick

• One image, many environments at runtime → Option A.
• One image per environment, built in CI → Option B.