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 ```bash 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. ```tsx '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} /> ) }) ``` ```tsx '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 ```tsx '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 ```tsx '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: ```tsx import { QueryErrorBoundary } from '@suspensive/react-query-4' const Example = () => ( <QueryErrorBoundary> <PostsSection /> </QueryErrorBoundary> ) ``` Correct: ```tsx 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: ```tsx <ErrorBoundary fallback={({ error, reset }) => <button onClick={reset}>{error.message} — retry</button>}> <Suspense fallback={<Spinner />}> <SuspenseQuery {...postsQueryOptions()}>{({ data }) => <List data={data} />}</SuspenseQuery> </Suspense> </ErrorBoundary> ``` Correct: ```tsx 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.