suspensive-react

This skill builds on react-query. Read ../../react-query/SKILL.md first.

This skill covers only the seam between @suspensive/react-query-4 and @suspensive/react: error boundaries around suspense queries, query error resetting, and loading UX in fallbacks. The key fact: QueryErrorBoundary was removed in v3 (it forced a peerDependency on @suspensive/react; issues #1424, #1325, #1349) — you compose the replacement yourself from ErrorBoundary and TanStack Query's useQueryErrorResetBoundary (same import on TSQ v4 as v5).

Setup

npm install @suspensive/react-query-4 @suspensive/react @tanstack/react-query@4

Core Patterns

QueryErrorBoundary replacement (complete wiring)

Resetting the boundary alone is not enough: the query error is still cached, so remounting the children immediately rethrows it. Wire useQueryErrorResetBoundary().reset into onReset so both the boundary and the query error cache reset together, and expose the boundary's own reset in the fallback as the retry button.

'use client'

import { ErrorBoundary } from '@suspensive/react'
import { useQueryErrorResetBoundary } from '@tanstack/react-query'
import { type ComponentPropsWithoutRef, type ComponentRef, forwardRef } from 'react'

export const QueryErrorBoundary = forwardRef<
  ComponentRef<typeof ErrorBoundary>,
  ComponentPropsWithoutRef<typeof ErrorBoundary>
>(({ onReset, ...props }, resetRef) => {
  const { reset } = useQueryErrorResetBoundary()
  return (
    <ErrorBoundary
      {...props}
      onReset={() => {
        onReset?.()
        reset()
      }}
      ref={resetRef}
    />
  )
})

'use client'

import { Suspense } from '@suspensive/react'
import { SuspenseQuery } from '@suspensive/react-query-4'
import { QueryErrorBoundary } from '~/components/QueryErrorBoundary'
import { postsQueryOptions } from '~/queries'

export const PostsSection = () => (
  <QueryErrorBoundary
    fallback={({ error, reset }) => (
      <div>
        <p>{error.message}</p>
        <button onClick={reset}>retry</button>
      </div>
    )}
  >
    <Suspense fallback={<div>Loading posts...</div>}>
      <SuspenseQuery {...postsQueryOptions()}>
        {({ data: posts }) => posts.map((post) => <div key={post.id}>{post.title}</div>)}
      </SuspenseQuery>
    </Suspense>
  </QueryErrorBoundary>
)

Clicking retry calls the fallback's reset, which triggers onReset, which resets TanStack Query's error boundary state — so the remounted SuspenseQuery refetches instead of rethrowing the cached error.

shouldCatch: catch only API errors around SuspenseQuery

'use client'

import { ErrorBoundary, Suspense } from '@suspensive/react'
import { SuspenseQuery } from '@suspensive/react-query-4'
import { useQueryErrorResetBoundary } from '@tanstack/react-query'
import { userQueryOptions } from '~/queries'

class ApiError extends Error {
  constructor(
    public status: number,
    message: string
  ) {
    super(message)
  }
}

export const UserSection = ({ userId }: { userId: number }) => {
  const { reset } = useQueryErrorResetBoundary()

  return (
    <ErrorBoundary
      shouldCatch={ApiError}
      onReset={reset}
      fallback={({ error, reset: retry }) => (
        <div>
          <p>API failed: {error.message}</p>
          <button onClick={retry}>retry</button>
        </div>
      )}
    >
      <Suspense fallback={<div>Loading user...</div>}>
        <SuspenseQuery {...userQueryOptions(userId)}>{({ data: user }) => <h1>{user.name}</h1>}</SuspenseQuery>
      </Suspense>
    </ErrorBoundary>
  )
}

Non-ApiError throws (render bugs) propagate past this boundary to an outer one, keeping API retry UI separate from crash UI. Make the queryFn throw typed errors (throw new ApiError(response.status, ...)) for this to filter correctly.

Delay inside the Suspense fallback

'use client'

import { Delay, Suspense } from '@suspensive/react'
import { SuspenseQuery } from '@suspensive/react-query-4'
import { postsQueryOptions } from '~/queries'

export const PostList = () => (
  <Suspense
    fallback={
      <Delay ms={200}>
        <div>Loading posts...</div>
      </Delay>
    }
  >
    <SuspenseQuery {...postsQueryOptions()}>
      {({ data: posts }) => posts.map((post) => <div key={post.id}>{post.title}</div>)}
    </SuspenseQuery>
  </Suspense>
)

Fast cache hits (under 200ms) show nothing instead of a spinner flash. Delay never extends how long the fallback stays visible — it only postpones exposing it.

Common Mistakes

[HIGH] Importing removed QueryErrorBoundary from Suspensive

Wrong:

import { QueryErrorBoundary } from '@suspensive/react-query-4'

const Example = () => (
  <QueryErrorBoundary>
    <PostsSection />
  </QueryErrorBoundary>
)

Correct:

import { ErrorBoundary } from '@suspensive/react'
import { useQueryErrorResetBoundary } from '@tanstack/react-query'

const Example = () => {
  const { reset } = useQueryErrorResetBoundary()
  return (
    <ErrorBoundary
      onReset={reset}
      fallback={({ error, reset: retry }) => <button onClick={retry}>{error.message} — retry</button>}
    >
      <PostsSection />
    </ErrorBoundary>
  )
}

QueryErrorBoundary forced a peerDependency on @suspensive/react for a trivial implementation, so v3 removed it in favor of composing ErrorBoundary with useQueryErrorResetBoundary. Removed in v3, but agents trained on older code still generate this. Source: docs/suspensive.org/src/content/en/docs/react-query/migration/migrate-to-v3.mdx (#1424)

[HIGH] Retry button resets boundary but not query error

Wrong:

<ErrorBoundary fallback={({ error, reset }) => <button onClick={reset}>{error.message} — retry</button>}>
  <Suspense fallback={<Spinner />}>
    <SuspenseQuery {...postsQueryOptions()}>{({ data }) => <List data={data} />}</SuspenseQuery>
  </Suspense>
</ErrorBoundary>

Correct:

const { reset } = useQueryErrorResetBoundary()

<ErrorBoundary
  onReset={reset}
  fallback={({ error, reset: retry }) => (
    <button onClick={retry}>{error.message} — retry</button>
  )}
>
  <Suspense fallback={<Spinner />}>
    <SuspenseQuery {...postsQueryOptions()}>
      {({ data }) => <List data={data} />}
    </SuspenseQuery>
  </Suspense>
</ErrorBoundary>

Boundary reset only remounts the children; the query error is still in TanStack Query's cache, so the remounted suspense query rethrows it instantly and never refetches — resetting both is required. Source: https://github.com/toss/suspensive/issues/91

See also: ../../react-query/declarative-queries/SKILL.md for SuspenseQuery itself, ../../react-query/mutations/SKILL.md for v4 mutation result naming (isLoading, not isPending), @suspensive/react skills/react/error-handling for shouldCatch/resetKeys/ErrorBoundaryGroup, @suspensive/react skills/react/loading-ux for Delay and isDelayed fades.