TS2883: Type declarations break with TypeScript nodenext module resolution

[HalfLegend]

Describe the bug

Issue: @tanstack/react-query types break with TypeScript nodenext module resolution (TS2883)

Environment

• TypeScript: 6.0.3
• @tanstack/react-query: 5.101.0
• @tanstack/query-core: 5.101.0
• Module: nodenext
• ModuleResolution: nodenext

Description

When using TypeScript with module: "nodenext", any exported function that infers its return type from @tanstack/react-query hooks fails with TS2883:

The inferred type of 'useChunkTag' cannot be named without a reference to 
'QueryObserverResult' from '../../../../../../node_modules/@tanstack/query-core/build/modern/_tsup-dts-rollup.cjs'.

Root Cause

The issue is in how the type declaration files are structured:

ESM entry (index.d.ts):

export { QueryObserverResult } from './_tsup-dts-rollup.js';  // ✅ Correct .js extension

CJS entry (index.d.cts):

export { QueryObserverResult } from './_tsup-dts-rollup.cjs';  // CJS path

When TypeScript generates .d.ts declarations for functions with inferred return types in nodenext mode, it incorrectly resolves through the CJS path (_tsup-dts-rollup.cjs) instead of the ESM path (_tsup-dts-rollup.js). Since .cjs is not a valid ESM import path, TypeScript cannot generate a valid type reference and throws TS2883.

Reproduction

// hooks.ts
import { useQuery } from "@tanstack/react-query";

// This function has an inferred return type that depends on @tanstack types
export function useMyHook() {
  const query = useQuery({ queryKey: ['test'], queryFn: () => 'hello' });
  return { data: query.data };
}

With tsconfig.json:

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "declaration": true
  }
}

Running tsc will produce TS2883 errors.

Workaround

Explicitly declare return types to avoid TypeScript inference:

export function useMyHook(): { data: string | undefined } {
  const query = useQuery({ queryKey: ['test'], queryFn: () => 'hello' });
  return { data: query.data };
}

Expected Behavior

Types should work correctly with nodenext module resolution, as this is the recommended setting for Node.js applications and libraries.

Your minimal, reproducible example

.

Steps to reproduce

// hooks.ts
import { useQuery } from "@tanstack/react-query";

// This function has an inferred return type that depends on @tanstack types
export function useMyHook() {
  const query = useQuery({ queryKey: ['test'], queryFn: () => 'hello' });
  return { data: query.data };
}

With tsconfig.json:

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "declaration": true
  }
}

Running tsc will produce TS2883 errors.

Expected behavior

Types should work correctly with nodenext module resolution, as this is the recommended setting for Node.js applications and libraries.

How often does this bug happen?

None

Screenshots or Videos

No response

Platform

Windows 11

Tanstack Query adapter

None

TanStack Query version

v5.101.0

TypeScript version

v6.0.3

Additional context

No response

[thribhuvan003]

hit this too on nodenext. it traces back to the tsup experimentalDts setup in scripts/getTsupConfig.js — it rolls the declarations into _tsup-dts-rollup.d.ts/.d.cts and re-exports from them, so when a consumer has an inferred return type that needs to name something like QueryObserverResult, tsc chases the re-export down into that internal _tsup-dts-rollup.cjs file and can't name it portably → TS2742/2883. attw stays green because it only checks the public entry points, not inferred-type naming a level down.

the only clean fixes i can find are dropping experimentalDts for the stable dts (which gets rid of the shared rollup file), or waiting on a tsup fix for the rollup paths. happy to try the build swap across the packages if you're open to that direction — just didn't want to throw up a big build-config PR without a nod first.