Declarative Queries
Developmentdeclarative-queriesDeclarative Queries is an Agent Skill for development published in the toss/suspensive repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
SuspenseQuery, SuspenseQueries, SuspenseInfiniteQuery render-prop components for fetching in JSX without hook wrapper components. Load when placing queries at the same depth as Suspense/ErrorBoundary, running parallel queries, using select, integrating queryOptions/infiniteQueryOptions, or replacing useSuspenseQuery wrapper components.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/toss/suspensive/blob/HEAD/packages/react-query-5/skills/react-query/declarative-queries/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/declarative-queries, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
This skill builds on react-query. Read ../SKILL.md first.
SuspenseQuery/SuspenseQueries/SuspenseInfiniteQuery move data fetching into JSX so what suspends is visible at the same depth as the Suspense and ErrorBoundary handling it, and child components stay presentational.
Setup
npm install @suspensive/react-query-5 @suspensive/react @tanstack/react-query@5
Components come from '@suspensive/react-query-5'; queryOptions/infiniteQueryOptions come from '@tanstack/react-query'.
Core Patterns
Parallel queries at one depth with SuspenseQuery
'use client'
import { ErrorBoundary, Suspense } from '@suspensive/react'
import { SuspenseQuery } from '@suspensive/react-query-5'
import { PostListItem, UserProfile } from '~/components'
import { postsQueryOptions, userQueryOptions } from '~/queries'
export const PostsPage = ({ userId }: { userId: number }) => (
<ErrorBoundary fallback={({ error }) => <>{error.message}</>}>
<Suspense fallback={'loading...'}>
<SuspenseQuery {...userQueryOptions(userId)}>
{({ data: user }) => <UserProfile key={user.id} {...user} />}
</SuspenseQuery>
<SuspenseQuery {...postsQueryOptions(userId)} select={(posts) => posts.filter(({ isPublic }) => isPublic)}>
{({ data: posts }) => posts.map((post) => <PostListItem key={post.id} {...post} />)}
</SuspenseQuery>
</Suspense>
</ErrorBoundary>
)
Both queries fetch in parallel; the boundary scope is obvious because both sources of suspension sit directly under Suspense.
Combined results with SuspenseQueries
'use client'
import { ErrorBoundary, Suspense } from '@suspensive/react'
import { SuspenseQueries } from '@suspensive/react-query-5'
import { PostListItem, UserProfile } from '~/components'
import { postsQueryOptions, userQueryOptions } from '~/queries'
export const PostsPage = ({ userId }: { userId: number }) => (
<ErrorBoundary fallback={({ error }) => <>{error.message}</>}>
<Suspense fallback={'loading...'}>
<SuspenseQueries queries={[userQueryOptions(userId), postsQueryOptions(userId)]}>
{([{ data: user }, { data: posts }]) => (
<>
<UserProfile {...user} />
{posts.map((post) => (
<PostListItem key={post.id} {...post} />
))}
</>
)}
</SuspenseQueries>
</Suspense>
</ErrorBoundary>
)
Use SuspenseQueries when one render needs both results together (useSuspenseQueries in JSX).
Infinite scrolling with SuspenseInfiniteQuery
'use client'
import { ErrorBoundary, Suspense } from '@suspensive/react'
import { SuspenseInfiniteQuery } from '@suspensive/react-query-5'
import { infiniteQueryOptions } from '@tanstack/react-query'
import { PostListItem } from '~/components'
import { getPosts } from '~/api'
const postsInfiniteQueryOptions = (userId: number) =>
infiniteQueryOptions({
queryKey: ['users', userId, 'posts'],
queryFn: ({ pageParam }) => getPosts(userId, pageParam),
getNextPageParam: (lastPage) => lastPage.nextCursor,
initialPageParam: 0,
})
export const InfinitePostsPage = ({ userId }: { userId: number }) => (
<ErrorBoundary fallback={({ error }) => <>{error.message}</>}>
<Suspense fallback={'loading...'}>
<SuspenseInfiniteQuery {...postsInfiniteQueryOptions(userId)}>
{({ data, fetchNextPage, hasNextPage }) => (
<>
{data.pages.flatMap((page) => page.posts.map((post) => <PostListItem key={post.id} {...post} />))}
<button type="button" disabled={!hasNextPage} onClick={() => fetchNextPage()}>
Load More
</button>
</>
)}
</SuspenseInfiniteQuery>
</Suspense>
</ErrorBoundary>
)
Common Mistakes
[MEDIUM] Wrapper components created only to call useSuspenseQuery
Wrong:
const UserInfo = ({ userId }: { userId: number }) => {
const { data } = useSuspenseQuery(userQueryOptions(userId))
return <UserProfile {...data} />
}
Correct:
<SuspenseQuery {...userQueryOptions(userId)}>{({ data }) => <UserProfile {...data} />}</SuspenseQuery>
Hooks force an extra child component under Suspense whose name hides that it suspends; SuspenseQuery keeps fetching visible in JSX so only presentational components remain. Source: docs/suspensive.org/src/content/en/docs/react-query/motivation.mdx
[HIGH] SuspenseQuery without an ancestor Suspense
Wrong:
<SuspenseQuery {...postQueryOptions(id)}>{({ data }) => <Post data={data} />}</SuspenseQuery>
Correct:
<Suspense fallback={<PostSkeleton />}>
<SuspenseQuery {...postQueryOptions(id)}>{({ data }) => <Post data={data} />}</SuspenseQuery>
</Suspense>
The component suspends; with no boundary above it, suspension bubbles to the nearest ancestor Suspense or the app root, blanking unrelated UI. Source: https://github.com/toss/suspensive/issues/1654
[HIGH] Rendering SuspenseQuery in a React Server Component
Wrong:
// app/page.tsx — Server Component
import { SuspenseQuery } from '@suspensive/react-query-5'
export default function Page() {
return (
<SuspenseQuery queryKey={['posts']} queryFn={getPosts}>
{({ data }) => <PostList posts={data} />}
</SuspenseQuery>
)
}
Correct:
'use client'
import { SuspenseQuery } from '@suspensive/react-query-5'
export const Posts = () => (
<SuspenseQuery queryKey={['posts']} queryFn={getPosts}>
{({ data }) => <PostList posts={data} />}
</SuspenseQuery>
)
Render-prop children are functions and cannot cross the RSC serialization boundary; keep these components inside 'use client' modules. Source: https://github.com/toss/suspensive/issues/1563
[HIGH] Passing enabled or placeholderData to suspense queries
Wrong:
<SuspenseQuery queryKey={['user', userId]} queryFn={getUser} enabled={!!userId}>
{({ data }) => <UserProfile {...data} />}
</SuspenseQuery>
Correct:
{
userId ? (
<SuspenseQuery queryKey={['user', userId]} queryFn={() => getUser(userId)}>
{({ data }) => <UserProfile {...data} />}
</SuspenseQuery>
) : null
}
Suspense queries must guarantee data, so enabled/placeholderData are excluded from their option types — express conditionality with JSX instead. Source: docs/suspensive.org/src/content/en/docs/react-query/migration (v2 breaking changes)
[MEDIUM] Checking isLoading/isError on suspense query results
Wrong:
<SuspenseQuery {...postsQueryOptions()}>
{({ data, isLoading }) => (isLoading ? <Spinner /> : <List data={data} />)}
</SuspenseQuery>
Correct:
<SuspenseQuery {...postsQueryOptions()}>{({ data }) => <List data={data} />}</SuspenseQuery>
Suspense query result types have no loading/error branches — data is always the success type because Suspense and ErrorBoundary guarantee it, so guards are dead code.
Source: docs/suspensive.org/src/content/en/docs/react-query/motivation.mdx
See also: ../mutations/SKILL.md for Mutation in list rows, ../prefetching/SKILL.md to warm the cache before these components suspend, ../../compositions/suspensive-react/SKILL.md for ErrorBoundary reset wiring around SuspenseQuery.