>(`/api/users/${id}`)
revalidateTag(`user-${id}`)
return response.data
} catch (error) {
throw error
}
}
// Usage
// hooks/queries/useUser.ts
export function useUser(id: string) {
return useServerQuery({
queryKey: ["user", id],
queryFn: () => getUser(id),
})
}
```
### Error Handling
```tsx theme={null}
// in queries
const { isError, error, isLoadingError } = useQuery({
queryKey: [""],
queryFn: async () => 0,
})
useEffect(() => {
// handing error
}, [error])
// show different components
if (isError) {
return Error
}
if (isLoadingError) {
return Error
}
// in mutations
const customMutation = useMutation({
mutationFn: () => {},
onError: () => {
// error handing
},
})
```
### Query Key Management
```typescript theme={null}
// lib/utils/query-keys.ts
export const queryKeys = {
users: {
all: ["users"] as const,
detail: (id: string) => ["users", id] as const,
posts: (id: string) => ["users", id, "posts"] as const,
},
posts: {
all: ["posts"] as const,
detail: (id: string) => ["posts", id] as const,
},
} as const
```
## Using Prefetched Data with Hydration
### Key Concepts
1. **Prefetching Data**: Fetch data on the server using TanStack Query's `queryClient.prefetchQuery`.
2. **Hydration**: Pass server-fetched data to the client using the `dehydrate` and `Hydrate` APIs.
### Prefetch Data in a Page
In Next.js page (`page.tsx`), fetch data on the server and use `dehydrate` to serialize it for hydration:
```tsx theme={null}
// app/page.tsx
import {
HydrationBoundary,
dehydrate,
useQueryClient,
} from "@tanstack/react-query"
import { pokemonQueryOptions } from "@/lib/actions"
import PokemonList from "@/components/PokemonList"
export const revalidate = 0 // Disable ISR for simplicity
export default async function HomePage() {
// Prefetch data on the server
const queryClient = useQueryClient()
await queryClient.prefetchQuery(pokemonQueryOptions)
// Dehydrate the data
const dehydratedState = dehydrate(queryClient)
return (
)
}
```
### Fetch Data with TanStack Query
Create a utility to fetch data:
```tsx theme={null}
// lib/fetchers.ts
"use server"
export async function fetchPokemonList() {
const res = await fetch("https://pokeapi.co/api/v2/pokemon?limit=20")
if (!res.ok) throw new Error("Failed to fetch PokΓ©mon data")
return res.json()
}
```
In custom hook, use `useQuery` to access the hydrated data:
```tsx theme={null}
// feature-tag/queries.ts
"use client"
import { useQuery, queryOptions } from "@tanstack/react-query"
import { fetchPokemonList } from "@/lib/features/pokemon/actions"
export const pokemonQueryOptions = queryOptions({
queryKey: ["pokemon"],
queryFn: fetchPokemonList,
})
export default const usePokemonList = () => {
return useQuery(pokemonQueryOptions)
}
```
```tsx theme={null}
// app/components/PokemonList.tsx
"use client"
import { usePokemonList } from "@/lib/features/pokemon/queries"
export default function PokemonList() {
const { data, isLoading, isError } = usePokemonList()
if (isLoading) return Loading...
if (isError) return Error fetching PokΓ©mon data
return (
{data.results.map((pokemon: { name: string }, index: number) => (
-
{pokemon.name}
))}
)
}
```
## Optimistic Updates
### 1: Make a Server Action
```typescript theme={null}
// actions.ts
"use server" // This is a server action
import {api} from "@/lib/config/api-client"
import {Experience, ExperienceMutation, ExperienceMutationSchema, ExperienceSchema} from "@/lib/experience/types"
export const addExperienceToDB = async (experienceValues: ExperienceMutation): Promise => {
const params = ExperienceMutationSchema.parse(experienceValues)
const data = await api.post("/resume/base/experience/", params)
return ExperienceSchema.parse(data)
};
```
### 2: Create a Custom Hook for Optimistic Updates
```typescript theme={null}
// mutations.ts
import {Experience, ExperienceMutation} from '@/lib/experience/types'
import {MutationOptions, useMutation} from '@tanstack/react-query'
import {deleteExperienceFromDB, addExperienceToDB} from '@/lib/experience/actions'
export const useAddUserExperienceMutation = (options?: MutationOptions) => useMutation(
{
mutationFn: addExperienceToDB,
...options // Open Close Principle - Open for extension, closed for modification
}
)
export const useDeleteExperienceMutation = (options?:MutationOptions) => useMutation({
mutationFn: (experienceId) => deleteExperienceFromDB(experienceId, 'base'),
...options
})
```
### 3: Make Reuseable Query Options
```tsx theme={null}
// queries.ts
import {queryOptions, useQuery} from '@tanstack/react-query'
import {EXPERIENCE_KEYS} from './keys' //
import {getExperiencesFromDB} from './actions'
export const experienceQueryOptions = queryOptions({
queryKey: EXPERIENCE_KEYS,
queryFn: () => getExperiencesFromDB('base')
})
// not needed for optimistic updates
export const useCurrentExperiences = () => useQuery(experienceQueryOptions)
```
### 3: Use the Hook in a Component
```tsx theme={null}
'use client' // This is a client side component
const queryClient = useQueryClient()
// hook in action
const {mutateAsync, isPending} = useAddUserExperienceMutation({
onMutate: async (newExperience) => {
// Cancel any outgoing re-fetches
// (so they don't overwrite our optimistic update)
await queryClient.cancelQueries(experienceQueryOptions)
// Snapshot the previous value
const prevExperiences = queryClient.getQueryData(experienceQueryOptions.queryKey)
// Optimistically update to the new value
queryClient.setQueryData(experienceQueryOptions.queryKey, (oldData:any) => oldData ? [...oldData, newExperience] : oldData)
// TODO remove this any the
// Return a context object with the snapshotted value
return {prevExperiences}
},
// If the mutation fails,
// use the context returned from onMutate to roll back
// TODO remove this any the
onError: (err, newExperience, context:any) => {
queryClient.setQueryData(experienceQueryOptions.queryKey, context?.prevExperiences)
throw Error('Failed to add experience')
},
// Always refetch after error or success:
onSettled: () => {
queryClient.invalidateQueries(experienceQueryOptions)
}
})
// handle mutation
const handleSubmit = async (values: ExperienceMutation) => {
try {
await mutateAsync(values)
} catch (error) {
toast.error('Failed to add experience')
}
}
```
For more details, refer to the following links.
* [Example Repo](https://github.com/sahilverma-dev/tanstack-query-nextjs14-example)
* [Server Rendering & Hydration](https://tanstack.com/query/latest/docs/framework/react/guides/ssr)
* [Advanced Server Rendering](https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr)
* [Next 14 + React Query COMBO with Server Actions and RSC](https://www.youtube.com/watch?v=yVsaCVEfPn4)
* [TanStack Query docs](https://tanstack.com/query)
* [Next.js App Router docs](https://nextjs.org/docs/app)
## Reference
* [Bullet Proof React - Next JS](https://github.com/alan2207/bulletproof-react/blob/master/apps/nextjs-app/)
* [Design Patterns in React](https://www.youtube.com/playlist?list=PLApy4UwQM3Updrw-4mOXTwgsWar9bqk6i)
## Overview
This architecture provides a robust solution for data fetching in Next.js applications by combining Server Actions with TanStack Query. We use this in our Letraz's client side code. Key features:
* π Seamless server-side and client-side data fetching
* π¦ Efficient caching and revalidation
* π‘οΈ Type-safe API interactions
* π¨ Comprehensive error handling
* π― Feature-based organization
* βΎοΈ Built-in support for infinite scrolling