TanStack · TkDodo · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/.changeset/fix-query-options-declaration-emit.md b/.changeset/fix-query-options-declaration-emit.md
@@ -0,0 +1,11 @@
+---
+'@tanstack/query-core': patch
+'@tanstack/angular-query-experimental': patch
+'@tanstack/preact-query': patch
+'@tanstack/react-query': patch
+'@tanstack/solid-query': patch
+'@tanstack/svelte-query': patch
+'@tanstack/vue-query': patch
+---
+
+Fix `queryOptions` and `infiniteQueryOptions` return types so exported inferred options can be emitted in declaration files without leaking internal data tag symbols.
diff --git a/integrations/vue-declaration-emit/consumer/query-options.ts b/integrations/vue-declaration-emit/consumer/query-options.ts
@@ -0,0 +1,9 @@
+import{
+definedInitialDataOptions,
+undefinedInitialDataOptions,
+}from'../dist/query-options.js'
+
+exportconstoptions={
+ definedInitialDataOptions,
+ undefinedInitialDataOptions,
+}
diff --git a/integrations/vue-declaration-emit/package.json b/integrations/vue-declaration-emit/package.json
@@ -0,0 +1,26 @@
+{
+ "name": "vue-declaration-emit",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "test:types": "pnpm run test:types:ts6 && pnpm run test:types:ts7",
+ "test:types:ts6": "node ../../node_modules/typescript/lib/tsc.js --pretty false --project tsconfig.emit.json && node ../../node_modules/typescript/lib/tsc.js --pretty false --project tsconfig.consume.json",
+ "test:types:ts7": "node ../../node_modules/typescript70/lib/tsc.js --pretty false --project tsconfig.emit.json && node ../../node_modules/typescript70/lib/tsc.js --pretty false --project tsconfig.consume.json"
+ },
+ "dependencies": {
+ "@tanstack/vue-query": "workspace:*",
+ "vue": "^3.4.27"
+ },
+ "devDependencies": {
+ "typescript": "5.8.3"
+ },
+ "nx": {
+ "targets": {
+ "test:types": {
+ "dependsOn": [
+ "^build"
+ ]
+ }
+ }
+ }
+}
diff --git a/integrations/vue-declaration-emit/src/query-options.ts b/integrations/vue-declaration-emit/src/query-options.ts
@@ -0,0 +1,14 @@
+import { queryOptions } from '@tanstack/vue-query'
+
+/** @public */
+export const undefinedInitialDataOptions = queryOptions({
+ queryKey: ['undefined-initial-data'],
+ queryFn: async () => ({ value: 'data' }),
+})
+
+/** @public */
+export const definedInitialDataOptions = queryOptions({
+ queryKey: ['defined-initial-data'],
+ queryFn: async () => ({ value: 'data' }),
+ initialData: { value: 'initial data' },
+})
diff --git a/integrations/vue-declaration-emit/tsconfig.consume.json b/integrations/vue-declaration-emit/tsconfig.consume.json
@@ -0,0 +1,11 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "noEmit": true,
+ "skipLibCheck": false,
+ "strict": true
+ },
+ "include": ["./consumer"]
+}
diff --git a/integrations/vue-declaration-emit/tsconfig.emit.json b/integrations/vue-declaration-emit/tsconfig.emit.json
@@ -0,0 +1,13 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "declaration": true,
+ "emitDeclarationOnly": true,
+ "strict": true,
+ "rootDir": "./src",
+ "outDir": "./dist"
+ },
+ "include": ["./src"]
+}
diff --git a/packages/angular-query-experimental/src/__tests__/infinite-query-options.test-d.ts b/packages/angular-query-experimental/src/__tests__/infinite-query-options.test-d.ts
@@ -10,6 +10,15 @@ import type {
  InitialDataFunction,
 } from '@tanstack/query-core'
 
+// Regression test for exported infiniteQueryOptions inference under declaration emit.
+// TypeScript should be able to name the return type without expanding the
+// internal data tag symbols into the consumer's .d.ts output.
+export const exportedInfiniteQueryOptions = infiniteQueryOptions({
+ queryKey: ['invalid'],
+ getNextPageParam: () => 1,
+ initialPageParam: 1,
+})
+
 describe('infiniteQueryOptions', () => {
  it('should not allow excess properties', () => {
  const key = queryKey()

diff --git a/packages/angular-query-experimental/src/__tests__/query-options.test-d.ts b/packages/angular-query-experimental/src/__tests__/query-options.test-d.ts
@@ -9,6 +9,13 @@ import {
 } from '..'
 import type { Signal } from '@angular/core'
 
+// Regression test for exported queryOptions inference under declaration emit.
+// TypeScript should be able to name the return type without expanding the
+// internal data tag symbols into the consumer's .d.ts output.
+export const exportedQueryOptions = queryOptions({
+ queryKey: ['invalid'],
+})
+
 describe('queryOptions', () => {
  it('should not allow excess properties', () => {
  expectTypeOf(queryOptions).parameter(0).not.toHaveProperty('stallTime')

diff --git a/packages/angular-query-experimental/src/infinite-query-options.ts b/packages/angular-query-experimental/src/infinite-query-options.ts
@@ -1,11 +1,11 @@
 import type {
- DataTag,
  DefaultError,
  InfiniteData,
  InitialDataFunction,
  NonUndefinedGuard,
  OmitKeyof,
  QueryKey,
+ QueryKeyWithDataTag,
  SkipToken,
 } from '@tanstack/query-core'
 import type { CreateInfiniteQueryOptions } from './types'
@@ -105,9 +105,8 @@ export function infiniteQueryOptions<
  TData,
  TQueryKey,
  TPageParam
-> & {
- queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
-}
+> &
+ QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
 /**
  * Allows sharing and re-using infinite query options in a type-safe way.
@@ -136,9 +135,8 @@ export function infiniteQueryOptions<
  TData,
  TQueryKey,
  TPageParam
-> & {
- queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
-}
+> &
+ QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
 /**
  * Allows sharing and re-using infinite query options in a type-safe way.
@@ -167,9 +165,8 @@ export function infiniteQueryOptions<
  TData,
  TQueryKey,
  TPageParam
-> & {
- queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
-}
+> &
+ QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
 /**
  * Allows sharing and re-using infinite query options in a type-safe way.

diff --git a/packages/angular-query-experimental/src/query-options.ts b/packages/angular-query-experimental/src/query-options.ts
@@ -1,11 +1,11 @@
 import type {
- DataTag,
  DefaultError,
  InitialDataFunction,
  NonUndefinedGuard,
  OmitKeyof,
  QueryFunction,
  QueryKey,
+ QueryKeyWithDataTag,
  SkipToken,
 } from '@tanstack/query-core'
 import type { CreateQueryOptions } from './types'
@@ -80,9 +80,8 @@ export function queryOptions<
  TQueryKey extends QueryKey = QueryKey,
 >(
  options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
-): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & {
- queryKey: DataTag<TQueryKey, TQueryFnData, TError>
-}
+): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &
+ QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
 /**
  * Allows sharing and re-using query options in a type-safe way.
@@ -112,9 +111,8 @@ export function queryOptions<
  TQueryKey extends QueryKey = QueryKey,
 >(
  options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>,
-): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> & {
- queryKey: DataTag<TQueryKey, TQueryFnData, TError>
-}
+): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> &
+ QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
 /**
  * Allows sharing and re-using query options in a type-safe way.
@@ -144,9 +142,8 @@ export function queryOptions<
  TQueryKey extends QueryKey = QueryKey,
 >(
  options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
-): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & {
- queryKey: DataTag<TQueryKey, TQueryFnData, TError>
-}
+): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &
+ QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
 /**
  * Allows sharing and re-using query options in a type-safe way.

diff --git a/packages/preact-query/src/__tests__/infiniteQueryOptions.test-d.tsx b/packages/preact-query/src/__tests__/infiniteQueryOptions.test-d.tsx
@@ -12,6 +12,15 @@ import { useInfiniteQuery } from '../useInfiniteQuery'
 import { useQuery } from '../useQuery'
 import { useSuspenseInfiniteQuery } from '../useSuspenseInfiniteQuery'
 
+// Regression test for exported infiniteQueryOptions inference under declaration emit.
+// TypeScript should be able to name the return type without expanding the
+// internal data tag symbols into the consumer's .d.ts output.
+export const exportedInfiniteQueryOptions = infiniteQueryOptions({
+ queryKey: ['invalid'],
+ getNextPageParam: () => 1,
+ initialPageParam: 1,
+})
+
 describe('infiniteQueryOptions', () => {
  it('should not allow excess properties', () => {
  assertType(

diff --git a/packages/preact-query/src/__tests__/queryOptions.test-d.tsx b/packages/preact-query/src/__tests__/queryOptions.test-d.tsx
@@ -18,6 +18,13 @@ import { useQueries } from '../useQueries'
 import { useQuery } from '../useQuery'
 import { useSuspenseQuery } from '../useSuspenseQuery'
 
+// Regression test for exported queryOptions inference under declaration emit.
+// TypeScript should be able to name the return type without expanding the
+// internal data tag symbols into the consumer's .d.ts output.
+export const exportedQueryOptions = queryOptions({
+ queryKey: ['invalid'],
+})
+
 describe('queryOptions', () => {
  it('should not allow excess properties', () => {
  assertType(

diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -1,11 +1,11 @@
 import type {
- DataTag,
  DefaultError,
  InfiniteData,
  InitialDataFunction,
  NonUndefinedGuard,
  OmitKeyof,
  QueryKey,
+ QueryKeyWithDataTag,
  SkipToken,
 } from '@tanstack/query-core'
 
@@ -93,9 +93,8 @@ export function infiniteQueryOptions<
  TData,
  TQueryKey,
  TPageParam
-> & {
- queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
-}
+> &
+ QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
 export function infiniteQueryOptions<
  TQueryFnData,
@@ -117,9 +116,8 @@ export function infiniteQueryOptions<
  TData,
  TQueryKey,
  TPageParam
-> & {
- queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
-}
+> &
+ QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
 export function infiniteQueryOptions<
  TQueryFnData,
@@ -141,9 +139,8 @@ export function infiniteQueryOptions<
  TData,
  TQueryKey,
  TPageParam
-> & {
- queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
-}
+> &
+ QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
 export function infiniteQueryOptions(options: unknown) {
  return options

diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
@@ -1,11 +1,11 @@
 importtype{
-DataTag,
 DefaultError,
 InitialDataFunction,
 NonUndefinedGuard,
 OmitKeyof,
 QueryFunction,
 QueryKey,
+QueryKeyWithDataTag,
 SkipToken,
 }from'@tanstack/query-core'
 
@@ -57,9 +57,8 @@ export function queryOptions<
 TQueryKeyextendsQueryKey=QueryKey,
 >(
 options: DefinedInitialDataOptions<TQueryFnData,TError,TData,TQueryKey>,
-): DefinedInitialDataOptions<TQueryFnData,TError,TData,TQueryKey>&{
-queryKey: DataTag<TQueryKey,TQueryFnData,TError>
-}
+): DefinedInitialDataOptions<TQueryFnData,TError,TData,TQueryKey>&
+QueryKeyWithDataTag<TQueryKey,TQueryFnData,TError>
 
 exportfunctionqueryOptions<
 TQueryFnData=unknown,
@@ -68,9 +67,8 @@ export function queryOptions<
 TQueryKeyextendsQueryKey=QueryKey,
 >(
 options: UnusedSkipTokenOptions<TQueryFnData,TError,TData,TQueryKey>,
-): UnusedSkipTokenOptions<TQueryFnData,TError,TData,TQueryKey>&{
-queryKey: DataTag<TQueryKey,TQueryFnData,TError>
-}
+): UnusedSkipTokenOptions<TQueryFnData,TError,TData,TQueryKey>&
+QueryKeyWithDataTag<TQueryKey,TQueryFnData,TError>
 
 exportfunctionqueryOptions<
 TQueryFnData=unknown,
@@ -79,9 +77,8 @@ export function queryOptions<
 TQueryKeyextendsQueryKey=QueryKey,
 >(
 options: UndefinedInitialDataOptions<TQueryFnData,TError,TData,TQueryKey>,
-): UndefinedInitialDataOptions<TQueryFnData,TError,TData,TQueryKey>&{
-queryKey: DataTag<TQueryKey,TQueryFnData,TError>
-}
+): UndefinedInitialDataOptions<TQueryFnData,TError,TData,TQueryKey>&
+QueryKeyWithDataTag<TQueryKey,TQueryFnData,TError>
 
 exportfunctionqueryOptions(options: unknown){
 returnoptions

diff --git a/packages/query-core/src/types.ts b/packages/query-core/src/types.ts
@@ -79,6 +79,14 @@ export type DataTag<
  [dataTagErrorSymbol]: TError
  }
 
+export type QueryKeyWithDataTag<
+ TQueryKey extends QueryKey = QueryKey,
+ TQueryFnData = unknown,
+ TError = DefaultError,
+> = {
+ queryKey: DataTag<TQueryKey, TQueryFnData, TError>
+}
+
 export type InferDataFromTag<TQueryFnData, TTaggedQueryKey extends QueryKey> =
  TTaggedQueryKey extends DataTag<unknown, infer TaggedValue, unknown>
  ? TaggedValue

diff --git a/packages/react-query/src/__tests__/infiniteQueryOptions.test-d.tsx b/packages/react-query/src/__tests__/infiniteQueryOptions.test-d.tsx
@@ -11,6 +11,15 @@ import type {
  InitialDataFunction,
 } from '@tanstack/query-core'
 
+// Regression test for exported infiniteQueryOptions inference under declaration emit.
+// TypeScript should be able to name the return type without expanding the
+// internal data tag symbols into the consumer's .d.ts output.
+export const exportedInfiniteQueryOptions = infiniteQueryOptions({
+ queryKey: ['invalid'],
+ getNextPageParam: () => 1,
+ initialPageParam: 1,
+})
+
 describe('infiniteQueryOptions', () => {
  it('should not allow excess properties', () => {
  assertType(

diff --git a/packages/react-query/src/__tests__/queryOptions.test-d.tsx b/packages/react-query/src/__tests__/queryOptions.test-d.tsx
@@ -18,6 +18,13 @@ import type {
  QueryPersister,
 } from '@tanstack/query-core'
 
+// Regression test for exported queryOptions inference under declaration emit.
+// TypeScript should be able to name the return type without expanding the
+// internal data tag symbols into the consumer's .d.ts output.
+export const exportedQueryOptions = queryOptions({
+ queryKey: ['invalid'],
+})
+
 describe('queryOptions', () => {
  it('should not allow excess properties', () => {
  assertType(