Is suspense: true in useQuery intentionally allowed at runtime despite being removed from types in v5?

[ttaerrim]

Background

I'm migrating from v4 to v5 and discovered that the suspense option still works at runtime in useQuery, even though it's been removed from the TypeScript types.

The Issue

According to the v5 migration guide, the experimental suspense: boolean flag has been removed, and we should use useSuspenseQuery instead.

However, I found that the suspense option can still be used at runtime if you bypass TypeScript:

❌ This fails at compile time (as expected):

useQuery({
  queryKey: ['example'],
  queryFn: fetchData,
  suspense: true, // ❌ TypeScript error
})

✅ But this works at both compile time AND runtime:

const options = { 
  suspense: true,
  queryKey: ['example'],
  queryFn: fetchData,
}

useQuery(options) // ✅ No TypeScript error, works at runtime

Or using spread:

const baseOptions = { suspense: true }
useQuery({
  queryKey: ['example'],
  queryFn: fetchData,
  ...baseOptions, // ✅ TypeScript doesn't catch this
})

Why This Works

Looking at the source code:

1. Type level: UseQueryOptions omits 'suspense' from the base type

   // packages/react-query/src/types.ts
   export interface UseQueryOptions<...> extends OmitKeyof<
       UseBaseQueryOptions<...>,
       'suspense'  // 👈 Removed from types
     > {}

2. Runtime level: useBaseQuery still has all the suspense logic intact

   // packages/react-query/src/useBaseQuery.ts
   if (shouldSuspend(defaultedOptions, result)) {
     throw fetchOptimistic(defaultedOptions, observer, errorResetBoundary)
   }

3. Core level: query-core still supports the suspense option

   // packages/query-core/src/types.ts
   suspense?: boolean  // 👈 Still exists

Questions

1. Is this intentional? Should the runtime validation be added to prevent this bypass?
2. Is it safe to use during migration? We have a large codebase with many queries, and gradually migrating to useSuspenseQuery would be easier if we could temporarily use this pattern.
3. Will this be removed in v6? Should we avoid relying on this behavior?

Workaround for Large Migrations

For teams migrating large codebases, this pattern could be useful as a temporary bridge:

// Centralized query options factory
function createQueryOptions<T>(options: QueryOptions<T>) {
  return {
    ...options,
    suspense: true, // Temporarily until we migrate to useSuspenseQuery
  }
}

// Usage
useQuery(createQueryOptions({
  queryKey: ['example'],
  queryFn: fetchData,
}))

Environment

• @tanstack/react-query: v5.x
• TypeScript: 5.x
• React: 18.x

Would appreciate any guidance on whether this is a known issue or if there are better migration strategies! 🙏

[TkDodo]

it’s removed from types so use at your own risk.

[ttaerrim]

Thank you for the answer. 🥹