Support async createClientConfig for per-request client configuration (multi-tenant / SSR)

[looloosha]

Problem

When using @hey-api/client-fetch with runtimeConfigPath, the exported createClientConfig function is synchronous:

export type CreateClientConfig<T extends ClientOptions = ClientOptions2> =
  (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;

This works well for simple cases like setting a static baseUrl. However, in server-side multi-tenant applications (e.g. a Next.js app serving multiple brands), the client configuration depends on per-request data that requires async operations:

1. Base URL varies per brand — determined by the incoming request hostname (requires await headers() in Next.js App Router)
2. Auth token varies per session — fetched from an auth provider at request time (inherently async)

Current workaround

Since createClientConfig can't be async, the runtimeConfigPath feature is unusable for this scenario. Instead, we create a fresh client per request in a manual wrapper:

import { headers } from 'next/headers'
import { createClient, createConfig } from './bff-client/client/index'

const brandBaseUrls: Record<Brand, string | undefined> = {
  af: process.env.BFF_BASE_URL_AF,
  otf: process.env.BFF_BASE_URL_OTF,
}

export async function getBffClient() {
  const reqHeaders = await headers()
  const brand = await getBrand(reqHeaders)

  const auth = await getAuth()
  const tokenResponse = await auth.api.getAccessToken({
    body: { providerId: 'microsoft' },
    headers: reqHeaders,
  })
  const accessToken = tokenResponse?.accessToken

  return createClient(
    createConfig({
      baseUrl: brandBaseUrls[brand],
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    })
  )
}

Then every SDK call needs the client passed explicitly:

const client = await getBffClient()
const { data } = await getCurrentUser({ client })

This works, but it means:

• The singleton client exported from client.gen.ts is never used
• The runtimeConfigPath feature provides no value
• Every call site must remember to pass { client }

Proposal

It would be great if createClientConfig could optionally be async:

export type CreateClientConfig<T extends ClientOptions = ClientOptions2> =
  (override?: Config<ClientOptions & T>) =>
    Config<Required<ClientOptions> & T> | Promise<Config<Required<ClientOptions> & T>>;

Alternatively, a different mechanism that supports per-request configuration in server-side contexts would work too — for example, a clientProvider pattern or middleware-style hook that runs before each request.

Use case summary

Requirement	Why async is needed
Multi-tenant base URL	Brand is derived from request hostname (await headers() in Next.js)
Per-request auth token	Token is fetched from auth provider at request time
SSR / Server Components	Next.js App Router server components require async access to request context

Related

• Discussion Runtime environment variable for baseUrl for both server and client in Next.js #3033 covers a related angle (runtime env vars for Docker), but the core issue here is the sync-only constraint of createClientConfig blocking server-side per-request configuration.

Thanks for the great library! Happy to discuss alternative approaches.

[mrlubos]

Let's move this to issues #3444