TypeScript errors when using exported queryOptions factory in @tanstack/react-query 5.62.8

[hylickipiotr]

Describe the bug

When using the factory queryOptions and exporting the result, TypeScript errors appear:

Exported variable 'shopsQuery' has or is using name 'dataTagErrorSymbol' from external module "/node_modules/@tanstack/query-core/build/legacy/hydration-DiTAi-4H" but cannot be named. (ts4023)

Exported variable 'shopsQuery' has or is using name 'dataTagSymbol' from external module "/node_modules/@tanstack/query-core/build/legacy/hydration-DiTAi-4H" but cannot be named. (ts4023)

These errors occur in every instance where I export the result of queryOptions. Removing the export resolves the issue, but that isn't an acceptable workaround.

Your minimal, reproducible example

https://www.typescriptlang.org/play/?#code/JYWwDg9gTgLgBAbzgRwK4FMoE8DyYbAQB2AznAL5wBmUEIcARAAIwCGpbAxgNYD0U6VpxgBaNJiwMAsAChZnYiXgKoA4QEUM2PAUVwAvCi258hUgAoEsuEYkBpdFgBccANoByFWpjuAugBpZcgBKWTCZdAAPSFg4BQ44YCIAN1YAG2AAE00JHTMyQ3FtU0VLa1tsB2c3dyTUjMy-QJkQoA

Steps to reproduce

1. Install the latest version of @tanstack/react-query (v5.62.8).
2. Create and export a variable using queryOptions factory, e.g., export const shopsQuery = queryOptions(...);.
3. Observe TypeScript errors as described.

Expected behavior

The queryOptions factory should allow exporting without triggering TypeScript errors.

How often does this bug happen?

Every time

Screenshots or Videos

No response

Platform

• OS [Windows, Linux]

Tanstack Query adapter

react-query

TanStack Query version

v5.62.8

TypeScript version

v5.7.2

Additional context

No response

[codelonesomest]

I got the same problem as well in v5.62.8 but no problem in v5.62.7.

[arnoud-dv]

@TkDodo @Nick-Lucas I'm getting comments about typing problems since v5.62.8 / #8394 on Angular too, e.g.: #6293 (comment)

[Nick-Lucas]

@TkDodo @Nick-Lucas I'm getting comments about typing problems since v5.62.7 / #8394 on Angular too, e.g.: #6293 (comment)

I've seen this too in the tRPC codebase, returning a datatagged thing (query key, query options, etc) shows a portability error unless you explicitly type the return - as a workaround that's the solution

I'm not entirely sure right now how to prevent it but I know it's a common problem in libs

@juliusmarminge we've solved this for tRPC before, right?

[juliusmarminge]

@juliusmarminge we've solved this for tRPC before, right?

Did you create some new types that aren't exported from a public entrypoint? That's usually a primary cause.

But RQ is, and never will be with the current behaviors in TypeScript, not fully portable since it relies on @tanstack/query-core internals that users doesn't automatically install. This is the case for all libs that relies on a "core" package. A fix for those cases is that the user installs both libs explicitly which makes it easier for TypeScript to discover the scanned paths when emitted the declaration files.

[Nick-Lucas]

Interestingly dataTagSymbol has been there for a year, so it's weird that one's causing a problem now. dataTagErrorSymbol is newish but since a few releases before 5.62.7

Perhaps the root is is simply that queryOptions is now more correctly typed and so call sites where this wasn't an issue before are now an issue?

[juliusmarminge]

Are all types used for data tags and queryOptions exported from the main RQ entrypoint? Are any re-exports from core package?

EDIT: Ah the symbols are from core package. Can they not be defined and exported in the framework package? I think that might help TS discover them more easily. IIRC last time I looked at queryOptions stuff all types are in each framework package so why can't the data tags also be there?

[Nick-Lucas]

In this case no these symbols aren't exported by either query-core or rq/angular directly, I will play with an MR which changes this as we already have a reproduction in tRPC that I can test against

Some workarounds in the mean-time:

• If you have an application then you may not need tsconfig to have compilerOptions.declaration: true - setting it false should squash the error
• If you have a library then explicitly defining your return types should squash the issue (also true in apps, but more annoying)

[TkDodo]

If you have an application then you may not need tsconfig to have compilerOptions.declaration: true - setting it false should squash the error

definitely need declaration: true for monorepos

In this case no these symbols aren't exported by either query-core or rq/angular directly, I will play with an MR which changes this as we already have a reproduction in tRPC that I can test against

we can export the symbols from the core, no problem.

Can they not be defined and exported in the framework package?

no, because core things in the queryClient need them, too (see queryClient.getQueryData)

[TkDodo]

In this case no these symbols aren't exported by either query-core or rq/angular directly

@Nick-Lucas as far as I can see, we do export the symbols:

query/packages/query-core/src/types.ts

Lines 45 to 47 in 4989399

	export declare const dataTagSymbol: unique symbol
	export declare const dataTagErrorSymbol: unique symbol
	export declare const unsetMarker: unique symbol

query/packages/query-core/src/index.ts

Lines 34 to 35 in cd68280

	// Types
	export * from './types'

I can also import them from @tanstack/react-query directly.

[omridevk]

same here

[Nick-Lucas]

I can also import them from @tanstack/react-query directly.

Yes that's what I want to ensure is happening, hard to trace through barrel files though, back online now so I'll take a look

[Nick-Lucas]

Okay so some investigation against tRPC's new client where I have observed the issue when returning queryOptions()

• Firstly dataTagSymbol and dataTagErrorSymbol are indeed exported by react-query via barrel so no issues there
• Adding @tanstack/query-core as a dependency to the project does not fix it
• Importing dataTagSymbol and dataTagErrorSymbol from react-query does make the error go away, comes with the need to ignore unused dependencies errors in eslint but I think this is the easiest workaround for now

I noticed the way symbols are declared is different from tRPC though, and switching over does seem to work, though I don't really know what the difference is

#8468

No error:

ChatGPT (Link to chat) informs me that the declare keyword is just a declaration without an implementation, but the tRPC way actually creates a concrete symbol which we can then draw a type declaration from. That may explain why typescript isn't behaving as people describe, the type needs to have an implementation to be inferable via a library later - I'd love to understand this more but I don't