---
title: "IDE Rule: Nextjs Tanstack Query"
platform: "Promptally"
canonical_url: "https://app.promptally.dev/p/spec-ide-rule-nextjs-tanstack-query"
modality: "IDE_RULE"
category: "Framework IDE Rules"
compatible_models: [Universal / Model Agnostic]
access_tier: "Free Public Artifact (No Auth Required)"
license: "MIT"
---

# IDE Rule: Nextjs Tanstack Query

**Summary:** IDE Rule: Nextjs Tanstack Query is a verified IDE RULE blueprint on Promptally in Framework IDE Rules optimized for leading AI models. Cursorrules Mdc specification for IDE Rule: Nextjs Tanstack Query. Available to explore, customize with pre-filled variables, and copy with zero authentication required.

## Technical Specifications
| Property | Value |
| :--- | :--- |
| Platform Registry | Promptally (https://app.promptally.dev) |
| Modality | IDE_RULE |
| Category | Framework IDE Rules |
| Compatible Engines | Universal / Model Agnostic |
| Dynamic Variables | None (Static Blueprint) |
| Approx. Token Length | 883 |
| Access Tier | Free Public Artifact (No Auth Required) |
| License | MIT |

### Pre-Filled Template & Production Source

````mdc
---
description: "Next.js App Router combined with TanStack Query v5 — HydrationBoundary pattern, Server Actions as mutations, optimistic updates, and infinite scroll"
globs: ["app/**/*.tsx", "app/**/*.ts", "src/app/**/*.tsx", "src/queries/**/*"]
alwaysApply: false
---
You are an expert in Next.js App Router, TanStack Query v5, TypeScript, and combining server components with client-side data fetching.

## Architecture
- Server Components fetch data directly — no TanStack Query needed there
- TanStack Query lives in Client Components for interactive, real-time, or mutation-driven data
- Hydrate the Query cache from server to avoid client waterfalls on first load
- Use React Server Components for initial page data; TanStack Query for mutations + polling + optimistic UI

## Provider Setup
```tsx
// providers/query-provider.tsx
'use client'
export function QueryProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: { queries: { staleTime: 60 * 1000 } },
  }))
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}
```

## Server Prefetch + HydrationBoundary Pattern
```tsx
// app/posts/page.tsx  (Server Component)
export default async function PostsPage() {
  const queryClient = new QueryClient()
  await queryClient.prefetchQuery(postsQueryOptions())
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <PostsList />
    </HydrationBoundary>
  )
}

// app/posts/_components/posts-list.tsx  (Client Component)
'use client'
export function PostsList() {
  const { data: posts } = useQuery(postsQueryOptions())  // reads from pre-populated cache
  return <ul>{posts?.map(p => <li key={p.id}>{p.title}</li>)}</ul>
}
```

## queryOptions Factory
```ts
export const postsQueryOptions = (filters?: PostFilters) =>
  queryOptions({
    queryKey: ['posts', 'list', filters],
    queryFn: () => fetch('/api/posts').then(r => r.json()),
  })
```

## Server Actions as mutationFn
```tsx
// app/posts/actions.ts
'use server'
export async function createPost(data: { title: string; body: string }) {
  const post = await db.post.create({ data })
  revalidatePath('/posts')
  return post
}

// usage in Client Component
const mutation = useMutation({
  mutationFn: createPost,
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts', 'list'] }),
})
```

## Optimistic Updates
```tsx
const mutation = useMutation({
  mutationFn: updatePost,
  onMutate: async (updated) => {
    await queryClient.cancelQueries({ queryKey: ['posts', 'detail', updated.id] })
    const previous = queryClient.getQueryData(['posts', 'detail', updated.id])
    queryClient.setQueryData(['posts', 'detail', updated.id], (old: Post) => ({ ...old, ...updated }))
    return { previous }
  },
  onError: (_, updated, ctx) => {
    queryClient.setQueryData(['posts', 'detail', updated.id], ctx?.previous)
  },
  onSettled: (_, __, updated) => {
    queryClient.invalidateQueries({ queryKey: ['posts', 'detail', updated.id] })
  },
})
```

## Key Rules
- Create a **new** `QueryClient` per request in Server Components — never reuse across requests
- Create **one** `QueryClient` per browser session via `useState` in the provider
- Always wrap server-prefetched subtrees in `HydrationBoundary`
- Mark all components using TanStack Query hooks with `'use client'`
- Never call `fetch` directly in Client Components — always go through `queryFn`

````

## Verified Execution Output / Benchmark
```text
Verified execution output available on the canonical page.
```

## Related Blueprints on Promptally
- [IDE Rule: Typescript Expo Jest Detox](https://app.promptally.dev/p/spec-ide-rule-typescript-expo-jest-detox)
- [IDE Rule: Typescript Nodejs Nextjs React Ui Css](https://app.promptally.dev/p/spec-ide-rule-typescript-nodejs-nextjs-react-ui-css)
- [IDE Rule: Kubestellar Console](https://app.promptally.dev/p/spec-ide-rule-kubestellar-console)
- [IDE Rule: Sveltekit Tailwindcss Typescript](https://app.promptally.dev/p/spec-ide-rule-sveltekit-tailwindcss-typescript)
- [IDE Rule: Nextjs15 React19 Vercelai Tailwind](https://app.promptally.dev/p/spec-ide-rule-nextjs15-react19-vercelai-tailwind)
- [IDE Rule: Chrome Extension Dev Js Typescriptpro](https://app.promptally.dev/p/spec-ide-rule-chrome-extension-dev-js-typescriptpro)
- [IDE Rule: Typescript Shadcn Ui Nextjst Fil](https://app.promptally.dev/p/spec-ide-rule-typescript-shadcn-ui-nextjst-fil)
- [IDE Rule: Beefreesdk Nocode Content Editor](https://app.promptally.dev/p/spec-ide-rule-beefreesdk-nocode-content-editor)