Провайдеры и клиентское состояние в App Router
На этой странице
Контекст, Zustand, Redux и TanStack Query работают только в клиентских компонентах, а корневой layout — серверный. Поэтому провайдеры выносят в отдельный файл app/providers.tsx с "use client" и оборачивают им children в layout: серверное содержимое при этом остаётся серверным. Главная ловушка — глобальный стор на уровне модуля: на сервере модуль живёт между запросами, и данные одного пользователя могут «утечь» к другому. Стор и QueryClient создают на каждый запрос / экземпляр приложения (useState(() => createStore()) или фабрика + контекст). Серверные данные лучше загружать в Server Components, а в клиентское состояние класть только то, что действительно клиентское: UI-состояние, черновики, корзину до оформления, фильтры (часто — в URL).
Вопрос
Как подключить контекст, Zustand или TanStack Query в Next.js App Router? Какие ошибки возникают с глобальным состоянием при SSR?
Файл провайдеров
// app/providers.tsx
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState } from 'react';
import { ThemeProvider } from './theme-provider';
export function Providers({ children }: { children: React.ReactNode }) {
// useState гарантирует один QueryClient на экземпляр приложения (и на каждый запрос при SSR)
const [queryClient] = useState(
() => new QueryClient({ defaultOptions: { queries: { staleTime: 60_000 } } }),
);
return (
<QueryClientProvider client={queryClient}>
<ThemeProvider>{children}</ThemeProvider>
</QueryClientProvider>
);
}// app/layout.tsx — остаётся серверным
import { Providers } from './providers';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="ru">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}children — это React-элементы, созданные на сервере. Клиентский провайдер их не «превращает» в клиентские: страницы по-прежнему Server Components.
Ставь провайдер как можно глубже: если контекст нужен только разделу /dashboard, подключи его в app/dashboard/layout.tsx, а не в корне.
Ловушка: стор на уровне модуля
// ✗ Опасно при SSR: один объект на весь сервер
import { create } from 'zustand';
export const useCart = create(() => ({ items: [] as CartItem[] }));Если такой стор заполнить на сервере данными пользователя (например, в серверном рендере клиентского компонента), следующий запрос другого пользователя может увидеть эти данные. Даже без утечки сервер и клиент начинают с разных состояний — несовпадение гидратации.
Правильно: стор на экземпляр + начальные данные с сервера
// stores/cart-store.ts
import { createStore } from 'zustand/vanilla';
export type CartState = { items: CartItem[]; add: (item: CartItem) => void };
export const createCartStore = (initial: CartItem[] = []) =>
createStore<CartState>()((set) => ({
items: initial,
add: (item) => set((s) => ({ items: [...s.items, item] })),
}));// stores/cart-provider.tsx
'use client';
import { createContext, useContext, useState } from 'react';
import { useStore } from 'zustand';
import { createCartStore, type CartState } from './cart-store';
const CartContext = createContext<ReturnType<typeof createCartStore> | null>(null);
export function CartProvider({ initialItems, children }: { initialItems: CartItem[]; children: React.ReactNode }) {
const [store] = useState(() => createCartStore(initialItems)); // один стор на экземпляр
return <CartContext value={store}>{children}</CartContext>;
}
export function useCart<T>(selector: (s: CartState) => T) {
const store = useContext(CartContext);
if (!store) throw new Error('useCart вне CartProvider');
return useStore(store, selector);
}// app/(shop)/layout.tsx — серверный: получает данные и передаёт начальное состояние
export default async function ShopLayout({ children }: { children: React.ReactNode }) {
const cart = await getCartForCurrentUser(); // cookies → БД
return <CartProvider initialItems={cart.items}>{children}</CartProvider>;
}TanStack Query с серверной предзагрузкой
// app/books/page.tsx — серверный
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';
export default async function Page() {
const queryClient = new QueryClient(); // новый на каждый запрос
await queryClient.prefetchQuery({ queryKey: ['books'], queryFn: fetchBooks });
return (
<HydrationBoundary state={dehydrate(queryClient)}>
<BookList /> {/* клиентский useQuery(['books']) сразу найдёт данные */}
</HydrationBoundary>
);
}Нужен ли Query, если есть Server Components? Для данных «только показать» — нет. Для клиентских обновлений, polling, бесконечной прокрутки, оптимистичных изменений и офлайн-сценариев — да.
Что где хранить
| Данные | Где |
|---|---|
| Каталог, профиль, заказы (для показа) | Server Components + кэш |
| Фильтры, сортировка, страница, вкладка | URL (searchParams) — переживают перезагрузку и шарятся |
| Тема, язык | Cookie (читается на сервере без вспышки) + контекст |
| Открытая модалка, раскрытый аккордеон | Локальный useState |
| Корзина, черновик формы, сложный клиентский UI | Zustand/Redux на экземпляр |
| Часто обновляемые серверные данные на клиенте | TanStack Query / SWR |
Частые ошибки
"use client"наlayout.tsxради провайдера — вся ветка превращается в клиентскую.const queryClient = new QueryClient()на уровне модуля в клиентском файле — общий кэш для всех запросов на сервере.- Дублирование серверных данных в глобальном сторе «на всякий случай».
- Чтение
localStorageпри рендере для начального состояния → несовпадение гидратации. Используй cookie,useSyncExternalStoreс серверным значением илиuse(browser())из React 19.3.
Мини-шпаргалка
app/providers.tsx ("use client") → <Providers>{children}</Providers> в layout
children остаются серверными
Стор/QueryClient — через useState(() => create...) на экземпляр, не на модуль
Начальное состояние — из серверного layout через props провайдера
Фильтры → URL, тема → cookie, серверные данные → RSC/Query
Провайдер — как можно глубже в дереве