Proposal: Migrate from openapi-typescript to @hey-api/openapi-ts

[Kevin-Ethiqais]

Describe the feature

I'd like to propose replacing openapi-typescript with @hey-api/openapi-ts.

From what I can see, openapi-typescript appears to have slowed down significantly in terms of maintenance, and this is starting to impact projects relying on recent TypeScript versions.

For example, there are currently several open discussions/issues around compatibility with newer TypeScript releases:
openapi-ts/openapi-typescript#2774
openapi-ts/openapi-typescript#2841
openapi-ts/openapi-typescript#2843

As a result, projects depending on openapi-typescript may end up being blocked from upgrading to newer major TypeScript versions until these issues are addressed.

@hey-api/openapi-ts seems to be a well-maintained successor with active development, regular releases, and a broader ecosystem (SDK generation, validation plugins, TanStack Query integrations, etc.). It is also largely compatible with the existing OpenAPI workflow while providing a clearer path for future maintenance.

Documentation:

https://heyapi.dev/docs/openapi/typescript/get-started
Would you be open to considering such a migration? I'd be happy to help evaluate the impact or even contribute to the migration if this proposal is considered worthwhile.

Additional information

• Would you be willing to help implement this feature?

Final checks

• Read the contribution guide.
• Check existing discussions and issues.

[Norbiros]

I was thinking about that a while ago too. If you have some free time, could you evaluate the migration? We could switch the backend to @hey-api/openapi-ts, but we have to preserve the current API overall vision - you still use typed Nuxt composables such as useFetch(path).

If that is possible without any weird quirks I like this decision, the module seems maintained, it is around half smaller etc.

[Kevin-Ethiqais]

Yes, no problem. I'll take a look at it one weekend when I have a bit of time.

[mrlubos]

@Kevin-Ethiqais tag me if you need anything from my side (if there are gaps)

[Oui-Dev]

Hey, I'm back here with my personal account. I took a quick look, and it looks more complicated than I thought.

The whole typed-composable design (usePets('/pet/{petId}', opts), $client(path), the [Client]RequestQuery/Body/Path/Response helpers, #open-fetch-schemas/[client]) depends on openapi-typescript's specific output shape: a paths object keyed by literal path strings, each keyed by HTTP method, each holding parameters/requestBody/responses in a very particular nested-by-status/media-type structure. src/runtime/fetch.ts and src/runtime/useFetch.ts build OpenFetchClient<Paths> / UseOpenFetchClient<Paths> directly on top of that shape using openapi-typescript-helpers (SuccessResponse, ErrorResponse, ResponseObjectMap, OperationRequestBodyContent, etc.).

From the @hey-api/typescript docs, typical output does not produce a paths-keyed type. It emits flat, per-operation named types instead (e.g. GetPetByIdData, GetPetByIdResponse, GetPetByIdErrors), meant to be consumed via the @hey-api/sdk plugin's generated function calls (petsApi.getPetById(...)). There's no built-in to index Paths['/pet/{petId}']['get'] out of that, which is exactly what useFetch(path) needs to infer params/response from a literal path argument.

So preserving useFetch(path) means we'd need to write a custom hey-api plugin that walks hey-api's IR and re-emits a paths/operations-equivalent .d.ts, essentially reimplementing the part of openapi-typescript we currently rely on, on a different toolchain. That's plausible given hey-api's plugin architecture, but it's a real ongoing piece of code to build and maintain, not a swapped import like I thought.

This would also inevitably entail breaking changes for users regarding the module configuration. openFetch.openAPITS is public API mapped 1:1 to openapi-typescript's Node options (pathParamsAsTypes, alphabetize, defaultNonNullable, rootTypes, etc.). None of these map onto hey-api's plugin options, so anyone using non-default openAPITS settings breaks on upgrade.

Interested in your take on the tradeoff: is migrating still attractive if it means maintaining a custom hey-api plugin (maybe @mrlubos can help) to preserve useFetch(path), or would you rather revisit this later?

My current lean is that the custom plugin cost makes this less attractive short-term, unless hey-api wants to support a paths-style export upstream.

[Norbiros]

Yeah, it is pretty obvious that it has to be a breaking change and that is okay. I would treat it as an experiment for now, there are multiple things that we can look into while rewriting to hey API:

• emit unjs/fetchdts types, which will be the default in nuxt 5
• add a way do you can get specific response body when you assert it's status code like feat: narrow type based on status code openapi-ts/openapi-typescript#1970

We might also need to wait for hey api 0.100.0