feat: Shared Client Core for Domain-Separated Multi-Output Generation

[Wonchang0314]

Description

First off, I really appreciate the current design philosophy of keeping each output as a self-contained, isolated unit — it makes individual outputs predictable and portable, and I think that's the right default.

That said, I just wonder if there's room for an providing another option which can share a single client bundle across domain-separated outputs.

The Situation

When generating multiple domain-specific outputs (e.g. payments, orders, users), the client/core/ and client/fetch/ files end up byte-for-byte identical in every output:

src/api/
  payments/
    client/   ← duplicated
    types.gen.ts
    sdk.gen.ts
  orders/
    client/   ← duplicated (identical)
    types.gen.ts
    sdk.gen.ts

As the number of domains grows, so does the redundancy — and it also means client configuration (base URL, auth headers, interceptors) has to be managed in multiple places.

What I'm Imagining

Something like a bundle: false option on the client plugin that references a shared output instead:

export default defineConfig([
  // Shared client — generated once
  {
    output: { path: 'src/api/client' },
    plugins: [{ name: '@hey-api/client-fetch', bundle: true }],
  },

  // Domain outputs — reference shared client
  {
    input: 'specs/payments.yaml',
    output: { path: 'src/api/payments' },
    plugins: [
      { name: '@hey-api/client-fetch', bundle: false, importFrom: '../client' },
      '@hey-api/typescript',
      '@hey-api/sdk',
    ],
  },
  // ...orders, users, etc.
]);

This would keep bundle: true as the default (no breaking change), and only opt into sharing when explicitly configured.

Why It Might Be Worth Considering

• No redundant files across outputs
• Single place to configure the client (interceptors, base URL, auth)
• Tree-shaking still works — each domain imports only what it needs
• Matches how teams naturally organize domain-separated frontends

Totally understand if this conflicts with the current architecture or is out of scope — just wanted to put it out there in case it resonates. Happy to dig into implementation implications if it's something worth exploring!

Environment

• @hey-api/openapi-ts: latest
• @hey-api/client-fetch: latest

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔}

[mrlubos]

@Wonchang0314 Hey! There are a few issues around this already and existing workarounds so you shouldn't be completely blocked.

That being said, this issue is probably the only one that has a sensible proposal. What would be the resulting folder tree for the client folder in your example? Where would client.gen.ts live and would there be one per input/output or one per run?

A few other constraints I can immediately think of:

• how could it handle single base domain vs users who want to use multiple domains? (e.g., 4 outputs and 2 shared clients)
• how could it handle one output that wants to use 2 clients? (one for most of the operations and one only for specific operations)

From the architecture design standpoint, the questions are:

• we currently "own" the output folder(s), i.e., they get deleted and generated on every run. Will this work with this new proposed design? My main concern is probably people targeting a folder higher in the tree and wiping half of their project haha
• could this or a similar design be extended to allow merging other outputs too? For example, what if we wanted to "lift" Zod schemas the same way so all outputs are located in a single folder? Clients are the obvious target because they're usually identical, but the same principle could apply to other areas

[Wonchang0314]

Thanks @mrlubos, that makes sense.

I think I understand the concerns around shared outputs, cleanup/ownership of generated directories, and the more complex client-sharing scenarios. After thinking about it more, it seems like solving this properly would likely require a much larger architectural change.

My use case was narrower: I mainly wanted a way to group the generated code more cleanly by domain. For that, I think I may use the existing SDK options such as operations.strategy: 'byTags' seems like a reasonable workaround without introducing a new output model.

Thanks for the explanation. If there’s room for contribution in this area later, I’d be interested in helping.