FEATURE-3879: added support for typescript isolatedDeclarations

[tompuric]

No description provided.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

@tpuric is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

⚠️ No Changeset found

Latest commit: b62f75d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pullfrog]

Important

The SDK plugin's new .returns(...) clause is appended unconditionally — for the Nuxt client this emits RequestResult<Responses, Errors, ThrowOnError>, but client-nuxt's RequestResult is parameterized as <TComposable, ResT, TError>. Regenerating any Nuxt SDK after this change will produce an annotation that doesn't match the runtime call's generics. Worth gating the new .returns(...) behind !isNuxtClient (or threading a Nuxt-specific shape through it) before merge.

TL;DR — Adds explicit return-type and field-type annotations across the core bundle templates and the SDK v1 emitter so generated output satisfies isolatedDeclarations, and enables declaration + isolatedDeclarations in several example tsconfig.json files to lock the contract in.

Key changes

• Annotate client bundle helpers — createQuerySerializer, setAuthParams, getUrl, path/object/primitive serializers, getValidRequestBody, and queryKeyJsonReplacer get explicit return types across client-angular, client-axios, client-core, client-fetch, client-ky, client-next, client-nuxt, and client-ofetch bundle templates.
• Type the generated client const and SDK operations — client-core/client.ts now imports a Client type symbol and annotates export const client: Client = createClient(...); the SDK v1 emitter (sdk/v1/node.ts, sdk/v1/plugin.ts) registers RequestResult as an external symbol and appends a .returns(client.RequestResult<Responses, Errors, ThrowOnError, [responseStyle?]>) clause to every operation function.
• Type a registry static field — enrichRootClass adds an explicit .type($.type(symbolRegistry).generic(symbol)) to the static readonly field so the class declaration is portable without inference.
• Enable isolatedDeclarations in examples — tsconfig.json in axios, fetch, ky, nestjs, next, openai (and others) adds "declaration": true, "isolatedDeclarations": true.
• Annotate example app code — example App.tsx, layout.tsx, page.tsx, tailwind.config.ts, pets.controller.ts, store.controller.ts, and openapi-ts.config.ts files get explicit return types (React.ReactNode, Promise<UserConfig>, etc.).

_{Summary ｜ 150 files ｜ 1 commit ｜ base: main ← support-typescript-isolated-declarations-3879}

Nuxt SDK return type uses the wrong generic shape

Before: implementFn produced operations with inferred return types, which TS was free to resolve through the Nuxt-specific RequestResult<TComposable, ResT, TError>.
After: .returns(client.RequestResult) is appended outside the $if(isNuxtClient, ...) branch with <Responses, Errors, ThrowOnError> generics — the positional argument shape that matches the non-Nuxt clients but not Nuxt.

packages/openapi-ts/src/plugins/@hey-api/client-nuxt/bundle/types.ts:92 declares RequestResult<TComposable extends Composable = '$fetch', ResT = unknown, TError = unknown>. The new emitter will pass an SDK's *Responses type as TComposable, which is structurally meaningless and will fail to extend Composable. The fix is to skip .returns(...) for Nuxt or to emit a different shape there — the existing $if(isNuxtClient, ...) block at the top of implementFn is the natural place.

sdk/v1/node.ts · client-nuxt/bundle/types.ts

Unrelated tsconfig.json flips in openapi-ts-next

Before: "allowJs": true in the Next example.
After: "allowJs": false alongside the new declaration / isolatedDeclarations flags.

allowJs has nothing to do with isolated declarations; flipping it scopes a behavior change that isn't motivated by the PR title. The example's postcss.config.mjs is the only .mjs and likely isn't in the program, so it probably still builds, but the flip is worth either reverting or calling out explicitly in the PR description.

examples/openapi-ts-next/tsconfig.json

Mechanical generated-file churn dominates the diff

Roughly 130 of the 150 files are regenerated .gen.ts outputs across 16 example projects — they reflect the source-side annotations and look internally consistent. The substantive review surface is the ~15 source files under packages/openapi-ts/src/plugins/@hey-api/. Worth running pnpm test to confirm the snapshot test suites under packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/clients/@hey-api/client-nuxt/** and other client snapshots are also regenerated — none of them appear in this diff, and they will diverge once this code lands.

client-core/client.ts · client-core/bundle/utils.ts · sdk/v1/plugin.ts

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[mrlubos]

@pullfrog reply to the comments

[pullfrog]

Replied to all three author responses on the prior review: acknowledged the allowJs flip as justified by isolatedDeclarations (suggested a PR-description note), explained the getValidRequestBody: unknown widening has no real caller impact (with a generic alternative if precision is desired), and pushed back on the Nuxt .returns(...) since the SDK emitter is shared and the unconditional clause still emits a broken shape into Nuxt-generated SDKs. No code changes were requested or made.

Task list (4/4 completed)

• Checkout PR branch
• Fetch comments on issue/PR 3880
• Investigate context for each thread
• Reply to each review thread

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

[mrlubos]

@tompuric will you update the snapshots?

[tompuric]

@tompuric will you update the snapshots?

Hey @mrlubos , I'm not familiar with contributing to the repo so I'll see how I can get the PR in shape 👍 Feel free to point me around or take control.

[mrlubos]

@tompuric should need just pnpm test:update and push committed changes

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 37.78%. Comparing base (c52c1a8) to head (b62f75d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3880      +/-   ##
==========================================
+ Coverage   37.73%   37.78%   +0.05%     
==========================================
  Files         582      582              
  Lines       20837    20857      +20     
  Branches     6066     6065       -1     
==========================================
+ Hits         7862     7880      +18     
- Misses      10567    10569       +2     
  Partials     2408     2408              

Flag	Coverage Δ
unittests	37.78% <ø> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mrlubos]

@tompuric now it gives you actual type errors. Does that not happen on your end when you said the current implementation works for you?

[tompuric]

When I say works for me, I mean when i yarn patch my changes into our repo it's 👍

• as for the pipelines within openapi-ts, that needs to be worked out as i'm touching plugins that i'm not using. Hence a demo PR I wanted to showcase for what I'm suggesting should be solved. Hope that makes sense

Edit: i'll see what I can do to get the PR ready here, but might not get to it until next week

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

npm i https://pkg.pr.new/@hey-api/codegen-core@3880

@hey-api/json-schema-ref-parser

npm i https://pkg.pr.new/@hey-api/json-schema-ref-parser@3880

@hey-api/nuxt

npm i https://pkg.pr.new/@hey-api/nuxt@3880

@hey-api/openapi-ts

npm i https://pkg.pr.new/@hey-api/openapi-ts@3880

@hey-api/shared

npm i https://pkg.pr.new/@hey-api/shared@3880

@hey-api/spec-types

npm i https://pkg.pr.new/@hey-api/spec-types@3880

@hey-api/types

npm i https://pkg.pr.new/@hey-api/types@3880

@hey-api/vite-plugin

npm i https://pkg.pr.new/@hey-api/vite-plugin@3880

commit: b62f75d

[tompuric]

This needs to be validated. Had trouble getting these two integrated.

Question: should these paths be covered?

[tompuric]

I've resolved this and have covered all areas in a cleaner/easier-to-read approach

[tompuric]

Hey @mrlubos , the PR is now in a ready state 🥳

I'm not sure how to improve the code coverage here for these changes so let me know if that's required.

Let me know how else I can assist with this, thanks 🙏

[tompuric]

Hey @mrlubos , apologies for the ping but hoping to have support for this so wondering how I can further assist the effort. PR is ready