Zustand و TanStack در پروژه های Next.js

Zustand و TanStack Query (که قبلاً React Query بود) چی هستن، فرقشون چیه و دقیقاً توی پروژه‌های Next.js (App Router یا Pages Router) کجا و چرا ازشون استفاده می‌کنیم.

۱. Zustand — برای Client State

چی هست؟

یک لایبرری خیلی سبک (کمتر از ۱ کیلوبایت!) برای مدیریت global state در ری‌اکت بدون boilerplate زیاد.

مزایای اصلی

• API خیلی ساده و تمیز (مثل hook معمولی)
• نیازی به Provider پیچیده نداره (ولی می‌تونی بذاری)
• عملکرد عالی (به‌روزرسانی فقط کامپوننت‌هایی که واقعاً از state استفاده کردن)
• پشتیبانی عالی از TypeScript
• middleware آماده (persist, devtools, immer و …)

مثال واقعی در Next.js

// store/useUserStore.ts
import { create } from 'zustand'
import { devtools, persist } from 'zustand/middleware'

type UserStore = {
  user: { name: string; role: string } | null
  isDarkMode: boolean
  setUser: (user: any) => void
  logout: () => void
  toggleDarkMode: () => void
}

export const useUserStore = create<UserStore>()(
  devtools(
    persist(
      (set) => ({
        user: null,
        isDarkMode: false,
        setUser: (user) => set({ user }),
        logout: () => set({ user: null }),
        toggleDarkMode: () => set((state) => ({ isDarkMode: !state.isDarkMode })),
      }),
      { name: 'user-storage' } // ذخیره در localStorage
    )
  )
)

کجا از Zustand استفاده کنیم؟ (در Next.js)

• تم دارک/لایت
• وضعیت لاگین کاربر (وقتی از cookie یا localStorage می‌خونی)
• تنظیمات کاربری (زبان، واحد پول و …)
• سبد خرید (اگر فقط کلاینت‌ساید باشه)
• حالت‌های UI (باز/بسته بودن سایدبار، modalها، فرم‌های چندمرحله‌ای)
• هر چیزی که “حالت کلاینت” هست و نیازی به کش سرور نداره

۲. TanStack Query — برای Server State

چی هست؟

بهترین ابزار موجود برای مدیریت داده‌های سمت سرور: fetch، cache، sync، refetch، pagination، mutation و …

مزایای اصلی

• کش هوشمند اتوماتیک
• refetch خودکار هنگام focus، reconnect، interval
• deduplication درخواست‌ها
• pagination و infinite scroll آماده
• mutation + optimistic update
• عالی کار کردن با Next.js App Router (Server Components + Client Components)

مثال واقعی در Next.js 13+ (App Router)

// app/products/page.tsx (Server Component)
async function getProducts() {
  const res = await fetch('https://api.example.com/products', { cache: 'no-store' })
  return res.json()
}

export default async function ProductsPage() {
  const products = await getProducts() // فقط اولین بار از سرور می‌گیره

  return <ProductsClient initialData={products} />
}

// app/components/ProductsClient.tsx (Client Component)
'use client'
import { useQuery, useInfiniteQuery } from '@tanstack/react-query'

export function ProductsClient({ initialData }) {
  const { data, isLoading, fetchNextPage, hasNextPage } = useInfiniteQuery({
    queryKey: ['products'],
    queryFn: ({ pageParam = 1 }) => fetch(`/api/products?page=${pageParam}`).then(res => res.json()),
    initialData: { pages: [initialData], pageParams: [1] },
    getNextPageParam: (lastPage) => lastPage.nextPage ?? undefined,
  })

  // اینجا کش می‌شه، refetch اتوماتیک داره، pagination و …
}

کجا از TanStack Query استفاده کنیم؟

• گرفتن لیست محصولات، پست‌ها، کامنت‌ها
• پروفایل کاربر از API
• هر نوع درخواست GET/POST/PUT/DELETE به بک‌اند
• pagination, infinite scroll
• وقتی می‌خوای داده‌ها همیشه به‌روز باشن (مثلاً چت، اعلان‌ها)

ترکیب ایده‌آل در Next.js App Router (بهترین روش ۲۰۲۵)

Server Components       → داده اولیه رو مستقیم از سرور بگیر (بدون کش کلاینت)
Client Components       → 
     ├─ TanStack Query   → برای داده‌های داینامیک، pagination، mutation
     └─ Zustand          → برای حالت‌های کلاینت (تم، سبد خرید محلی، UI state)

یه قانون طلایی

اگر داده از سرور میاد و ممکنه تغییر کنه → TanStack Query
اگر داده فقط توی مرورگر تولید/ذخیره می‌شه → Zustand

مثال واقعی ترکیب هر دو

// استفاده همزمان
function Header() {
  const user = useUserStore(state => state.user)           // Zustand
  const { data: notifications } = useQuery({               // TanStack Query
    queryKey: ['notifications', user?.id],
    enabled: !!user?.id,
  })

  return (
    <header>
      {user?.name} - اعلان‌ها: {notifications?.length}
    </header>
  )
}

خلاصه نهایی — کی از کدوم استفاده کنیم؟

اگه پروژه Next.js داری، ترکیب Zustand + TanStack Query الان (۲۰۲۵) بهترین و مدرن‌ترین ستاپه و تقریباً همه شرکت‌های بزرگ دارن ازش استفاده می‌کنن.

Zustand — مستندات و لینک‌های اصلی

Zustand یک لایبرری سبک برای مدیریت client state هست. مستنداتش خیلی ساده و کامله.

Zustand با Next.js — راهنماها و تیوترینال‌ها

برای Next.js (App Router و SSR)، این لینک‌ها عالی هستن. تمرکز روی جلوگیری از hydration errors و persist state.

TanStack Query — مستندات و لینک‌های اصلی

TanStack Query (قبلاً React Query) برای server state و caching عالیه. مستنداتش پر از مثال‌های React/Next.js هست.

TanStack Query با Next.js — راهنماها و تیوترینال‌ها

این لینک‌ها روی integration با App Router، SSR و hydration تمرکز دارن. عالی برای پروژه‌های واقعی.