Can you prevent generation of the singleton client object?

[thomasboyt]

I'm interested in using Hey API in a server-rendered Next.js app. Currently, my application uses a fetch wrapper that is instantiated for each request, which sets auth headers and a few other user-specific headers. I was thinking of doing the same in Hey API using a custom client created with createClient.

However, I noticed that by default, the generated SDK will just use a singleton client - the one exported from client.gen.ts. I don't want this to be an option - I think it could confuse other developers on my team, who might look at the type signature of the SDK and think that they don't need to pass in the custom client. I would much rather generate an SDK that requires passing in an instance of the client.

Is there a preferred way to generate a fetch client that doesn't include a singleton like this? Frankly, I think a singleton client is an antipattern for anything other than entirely client-side apps (and even then I'm not sure it's a great idea in most cases).

[dosubot[bot]]

Hi @thomasboyt! I'm Dosu and I’m helping the openapi-ts team.

Unfortunately, there's no built-in configuration option to disable the singleton client generation in Hey API. The generated code always includes the default client instance in client.gen.ts, and SDK functions use the pattern (options.client ?? client), making the client parameter optional.

Your workaround options:

1. Always pass custom clients explicitly - Create clients with createClient() per request and always pass them via the client option:

   const myClient = createClient({
     baseUrl: 'https://example.com',
     headers: { Authorization: `Bearer ${token}` },
   });
   
   const response = await getFoo({ client: myClient });

2. Use runtimeConfigPath for Next.js SSR - The @hey-api/client-next plugin has a runtimeConfigPath option that lets you customize client initialization, which is helpful for server/client environment differences.

3. Wrapper functions - Create your own wrapper module that re-exports SDK functions but requires the client parameter, hiding the auto-generated imports from your team.

Your feedback about the singleton being an antipattern for SSR is valid—you might consider opening a feature request on the Hey API repo for a "no singleton" mode or a way to make the client parameter required. This seems like a reasonable enhancement for server-side use cases.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

  

[mrlubos]

@thomasboyt hello, I see you over at openapi-typescript as well 👋 dosu is pretty much right, you can't disable the singleton output today, but you can enforce client to be always passed by setting client: false in the SDK plugin

[thomasboyt]

@mrlubos Oh, I think client: false fixes my biggest concern! I might add an ESLint rule to make sure developers don't import the singleton client from client.gen.ts as well.

It might be good to add a toggle to not generate client.gen.ts as well.

[mrlubos]

I never fully understood this requirement to pass client manually on every call, isn't that cumbersome? Do your developers create a new client instance for every single call? Can you share some snippet showing why this is necessary?

[thomasboyt]

Sure, the reason is interceptors (https://heyapi.dev/openapi-ts/clients/fetch#interceptors) in a server-side environment where multiple requests are being served at once.

We want to have an interceptor that adds a user's auth token to the request, so that the call site doesn't have to manually pass in an auth token header in every call. In a traditional client side application with a single user, you could just update the singleton client to set this header on all calls.

But in server-side logic, there are multiple different requests, each with their own user, being served at once. You can't just update the singleton client with the most recent user's auth token when you start serving the request, because if you start handling another user's new request simultaneously, it would overwrite the auth token, and you'd have users fetching things with incorrect authentication data.

Passing around a client provides isolation. And yes, it's slightly cumbersome, but a pretty common pattern. Traditionally you see this done in express apps or similar by having a middleware that injects an API client instance into the current request context that gets passed to every route handler, so it's easy to access the client.

[mrlubos]

That makes sense, thank you! Sounds like you're happy again? Or at least the issue was resolved

[thomasboyt]

Yep, I think I'm good for now! Thanks for the quick replies.

[programm-ingovals]

@mrlubos Since you asked about this specifically, there are some unique issues with next.js that I think need to be understood better in the hey api nextjs plugin.

I´m not sure if a singleton api client is just an antipattern for nextjs, or if it has its use cases. I think the nextjs plugin section could at lease benefit from a discussion about this, especially regarding interceptors. Especially if misuse could be a security risk.

[programm-ingovals]

See
https://github.com/orgs/hey-api/discussions/2269
https://github.com/orgs/hey-api/discussions/2996