State management in Next.js applications presents unique challenges that don't exist in plain React apps. The server/client boundary, React Server Components, and Next.js's built-in caching layer all influence how and where you manage state. Getting this wrong leads to hydration mismatches, unnecessary re-renders, and an architecture that fights the framework instead of leveraging it.
This tutorial walks through building production-grade state management in Next.js 14+ applications. We'll cover the built-in primitives first, then layer in Zustand and Redux Toolkit where they actually add value — not as defaults, but as tools you reach for when simpler approaches fall short.
Understanding the Next.js State Landscape
Next.js App Router fundamentally changes state management because it splits your application into server and client territories. Server Components can't hold state. Client Components can, but they shouldn't hold all of it.
Here's the mental model:
1Server State → fetch + cache (Next.js built-in)
2URL State → searchParams + useSearchParams
3Client State → useState/useReducer (local) or external stores (global)
4Form State → useFormState + useFormStatus (Server Actions)
5
Before reaching for any library, audit your state. In a typical Next.js e-commerce app we built, roughly 70% of what developers initially put in Redux was actually server state that belonged in fetch calls with proper cache tags.
Server State with Next.js Caching
The first category to handle is server state — data that originates from your API or database.
Basic Data Fetching in Server Components
typescript
1// app/products/page.tsx
2async function getProducts(category?: string): Promise<Product[]> {
3 const url = new URL('https://api.example.com/products');
4 if (category) url.searchParams.set('category', category);
5
6 const res = await fetch(url.toString(), {
7 next: { revalidate: 60, tags: ['products'] },
8 });
9
10 if (!res.ok) throw new Error(`Products fetch failed: ${res.status}`);
11 return res.json();
12}
13
14export default async function ProductsPage({
15 searchParams,
16}: {
17 searchParams: Promise<{ category?: string }>;
18}) {
19 const { category } = await searchParams;
20 const products = await getProducts(category);
21
22 return (
23 <div className="grid grid-cols-3 gap-4">
24 {products.map((product) => (
25 <ProductCard key={product.id} product={product} />
26 ))}
27 </div>
28 );
29}
30
This is zero-client-state data fetching. The page renders on the server, caches for 60 seconds, and can be invalidated by tag. No Redux needed.
Revalidation with Server Actions
typescript
1// app/actions/products.ts
2'use server';
3
4import { revalidateTag } from 'next/cache';
5
6export async function createProduct(formData: FormData) {
7 const product = {
8 name: formData.get('name') as string,
9 price: Number(formData.get('price')),
10 category: formData.get('category') as string,
11 };
12
13 const res = await fetch('https://api.example.com/products', {
14 method: 'POST',
15 headers: { 'Content-Type': 'application/json' },
16 body: JSON.stringify(product),
17 });
18
19 if (!res.ok) {
20 return { error: 'Failed to create product' };
21 }
22
23 revalidateTag('products');
24 return { success: true };
25}
26
typescript
1// app/products/CreateProductForm.tsx
2'use client';
3
4import { useActionState } from 'react';
5import { createProduct } from '@/app/actions/products';
6
7export function CreateProductForm() {
8 const [state, action, isPending] = useActionState(createProduct, null);
9
10 return (
11 <form action={action}>
12 <input name="name" required placeholder="Product name" />
13 <input name="price" type="number" required placeholder="Price" />
14 <select name="category">
15 <option value="electronics">Electronics</option>
16 <option value="clothing">Clothing</option>
17 </select>
18
19 <button type="submit" disabled={isPending}>
20 {isPending ? 'Creating...' : 'Create Product'}
21 </button>
22
23 {state?.error && <p className="text-red-500">{state.error}</p>}
24 {state?.success && <p className="text-green-500">Product created!</p>}
25 </form>
26 );
27}
28
useActionState handles the form submission state — loading, error, success — without any external library. The revalidateTag call ensures the product list updates everywhere it's displayed.
URL State Management
URL state is the most underused state management tool in Next.js. It's shareable, bookmarkable, survives refreshes, and works with the browser's back/forward buttons.
Building a Filter System with URL State
typescript
1// app/products/ProductFilters.tsx
2'use client';
3
4import { useRouter, useSearchParams, usePathname } from 'next/navigation';
5import { useCallback, useTransition } from 'react';
6
7interface FilterState {
8 category: string;
9 minPrice: string;
10 maxPrice: string;
11 sort: string;
12}
13
14export function ProductFilters() {
15 const router = useRouter();
16 const pathname = usePathname();
17 const searchParams = useSearchParams();
18 const [isPending, startTransition] = useTransition();
19
20 const currentFilters: FilterState = {
21 category: searchParams.get('category') ?? 'all',
22 minPrice: searchParams.get('minPrice') ?? '',
23 maxPrice: searchParams.get('maxPrice') ?? '',
24 sort: searchParams.get('sort') ?? 'newest',
25 };
26
27 const updateFilter = useCallback(
28 (key: keyof FilterState, value: string) => {
29 const params = new URLSearchParams(searchParams.toString());
30
31 if (value && value !== 'all') {
32 params.set(key, value);
33 } else {
34 params.delete(key);
35 }
36
37 // Reset to page 1 when filters change
38 params.delete('page');
39
40 startTransition(() => {
41 router.push(`${pathname}?${params.toString()}`);
42 });
43 },
44 [searchParams, pathname, router]
45 );
46
47 return (
48 <div className={`flex gap-4 ${isPending ? 'opacity-60' : ''}`}>
49 <select
50 value={currentFilters.category}
51 onChange={(e) => updateFilter('category', e.target.value)}
52 >
53 <option value="all">All Categories</option>
54 <option value="electronics">Electronics</option>
55 <option value="clothing">Clothing</option>
56 </select>
57
58 <input
59 type="number"
60 placeholder="Min Price"
61 value={currentFilters.minPrice}
62 onChange={(e) => updateFilter('minPrice', e.target.value)}
63 />
64
65 <input
66 type="number"
67 placeholder="Max Price"
68 value={currentFilters.maxPrice}
69 onChange={(e) => updateFilter('maxPrice', e.target.value)}
70 />
71
72 <select
73 value={currentFilters.sort}
74 onChange={(e) => updateFilter('sort', e.target.value)}
75 >
76 <option value="newest">Newest</option>
77 <option value="price-asc">Price: Low to High</option>
78 <option value="price-desc">Price: High to Low</option>
79 </select>
80 </div>
81 );
82}
83
The useTransition hook provides a loading state while the server re-renders the page with new search params. The URL becomes the single source of truth for filter state.
Custom Hook for Reusable URL State
typescript
1// lib/hooks/useQueryState.ts
2'use client';
3
4import { useRouter, useSearchParams, usePathname } from 'next/navigation';
5import { useCallback, useTransition } from 'react';
6
7type Serializer<T> = {
8 parse: (value: string) => T;
9 serialize: (value: T) => string;
10};
11
12const stringSerializer: Serializer<string> = {
13 parse: (v) => v,
14 serialize: (v) => v,
15};
16
17const numberSerializer: Serializer<number> = {
18 parse: (v) => Number(v),
19 serialize: (v) => String(v),
20};
21
22export function useQueryState<T = string>(
23 key: string,
24 options: {
25 defaultValue: T;
26 serializer?: Serializer<T>;
27 shallow?: boolean;
28 }
29) {
30 const router = useRouter();
31 const pathname = usePathname();
32 const searchParams = useSearchParams();
33 const [isPending, startTransition] = useTransition();
34
35 const serializer = (options.serializer ?? stringSerializer) as Serializer<T>;
36
37 const rawValue = searchParams.get(key);
38 const value = rawValue !== null ? serializer.parse(rawValue) : options.defaultValue;
39
40 const setValue = useCallback(
41 (newValue: T | null) => {
42 const params = new URLSearchParams(searchParams.toString());
43
44 if (newValue === null || newValue === options.defaultValue) {
45 params.delete(key);
46 } else {
47 params.set(key, serializer.serialize(newValue));
48 }
49
50 const newUrl = params.toString()
51 ? `${pathname}?${params.toString()}`
52 : pathname;
53
54 startTransition(() => {
55 router.push(newUrl, { scroll: false });
56 });
57 },
58 [searchParams, pathname, key, serializer, options.defaultValue, router]
59 );
60
61 return [value, setValue, isPending] as const;
62}
63
64// Usage
65export function PaginatedList() {
66 const [page, setPage, isNavigating] = useQueryState('page', {
67 defaultValue: 1,
68 serializer: numberSerializer,
69 });
70
71 return (
72 <div>
73 <p>Page: {page}</p>
74 <button onClick={() => setPage(page - 1)} disabled={page <= 1 || isNavigating}>
75 Previous
76 </button>
77 <button onClick={() => setPage(page + 1)} disabled={isNavigating}>
78 Next
79 </button>
80 </div>
81 );
82}
83
Local Client State with useReducer
For complex local state that doesn't need to be global, useReducer is often better than useState because it centralizes transitions and makes state changes predictable.
Multi-Step Form with useReducer
typescript
1// app/onboarding/useOnboardingForm.ts
2'use client';
3
4import { useReducer } from 'react';
5
6interface OnboardingState {
7 step: number;
8 data: {
9 companyName: string;
10 industry: string;
11 teamSize: string;
12 features: string[];
13 billingEmail: string;
14 plan: 'starter' | 'pro' | 'enterprise';
15 };
16 errors: Record<string, string>;
17 isSubmitting: boolean;
18}
19
20type OnboardingAction =
21 | { type: 'SET_FIELD'; field: string; value: string | string[] }
22 | { type: 'NEXT_STEP' }
23 | { type: 'PREV_STEP' }
24 | { type: 'SET_ERRORS'; errors: Record<string, string> }
25 | { type: 'SUBMIT_START' }
26 | { type: 'SUBMIT_SUCCESS' }
27 | { type: 'SUBMIT_ERROR'; error: string };
28
29const initialState: OnboardingState = {
30 step: 0,
31 data: {
32 companyName: '',
33 industry: '',
34 teamSize: '',
35 features: [],
36 billingEmail: '',
37 plan: 'starter',
38 },
39 errors: {},
40 isSubmitting: false,
41};
42
43function validateStep(step: number, data: OnboardingState['data']): Record<string, string> {
44 const errors: Record<string, string> = {};
45
46 switch (step) {
47 case 0:
48 if (!data.companyName.trim()) errors.companyName = 'Company name is required';
49 if (!data.industry) errors.industry = 'Select an industry';
50 break;
51 case 1:
52 if (!data.teamSize) errors.teamSize = 'Select team size';
53 if (data.features.length === 0) errors.features = 'Select at least one feature';
54 break;
55 case 2:
56 if (!data.billingEmail.includes('@')) errors.billingEmail = 'Valid email required';
57 break;
58 }
59
60 return errors;
61}
62
63function onboardingReducer(state: OnboardingState, action: OnboardingAction): OnboardingState {
64 switch (action.type) {
65 case 'SET_FIELD':
66 return {
67 ...state,
68 data: { ...state.data, [action.field]: action.value },
69 errors: { ...state.errors, [action.field]: '' },
70 };
71 case 'NEXT_STEP': {
72 const errors = validateStep(state.step, state.data);
73 if (Object.keys(errors).length > 0) {
74 return { ...state, errors };
75 }
76 return { ...state, step: state.step + 1, errors: {} };
77 }
78 case 'PREV_STEP':
79 return { ...state, step: Math.max(0, state.step - 1), errors: {} };
80 case 'SET_ERRORS':
81 return { ...state, errors: action.errors };
82 case 'SUBMIT_START':
83 return { ...state, isSubmitting: true };
84 case 'SUBMIT_SUCCESS':
85 return { ...state, isSubmitting: false, step: state.step + 1 };
86 case 'SUBMIT_ERROR':
87 return {
88 ...state,
89 isSubmitting: false,
90 errors: { submit: action.error },
91 };
92 default:
93 return state;
94 }
95}
96
97export function useOnboardingForm() {
98 const [state, dispatch] = useReducer(onboardingReducer, initialState);
99
100 return { state, dispatch };
101}
102
All state transitions are explicit. You can log every action for debugging, replay sequences, and test the reducer in isolation without rendering a component.
Need a second opinion on your mobile/frontend architecture?
I run free 30-minute strategy calls for engineering teams tackling this exact problem.
Book a Free CallZustand for Global Client State
When you genuinely need global client state — user preferences, shopping cart, notification queue — Zustand is the right tool for Next.js because it's lightweight (1.1KB), has no providers, and handles hydration well.
Setting Up Zustand with Next.js Hydration Safety
typescript
1// stores/cart-store.ts
2import { create } from 'zustand';
3import { persist, createJSONStorage } from 'zustand/middleware';
4import { immer } from 'zustand/middleware/immer';
5
6interface CartItem {
7 id: string;
8 name: string;
9 price: number;
10 quantity: number;
11 image: string;
12}
13
14interface CartState {
15 items: CartItem[];
16 isOpen: boolean;
17}
18
19interface CartActions {
20 addItem: (item: Omit<CartItem, 'quantity'>) => void;
21 removeItem: (id: string) => void;
22 updateQuantity: (id: string, quantity: number) => void;
23 clearCart: () => void;
24 toggleCart: () => void;
25 getTotal: () => number;
26 getItemCount: () => number;
27}
28
29export const useCartStore = create<CartState & CartActions>()(
30 persist(
31 immer((set, get) => ({
32 items: [],
33 isOpen: false,
34
35 addItem: (item) =>
36 set((state) => {
37 const existing = state.items.find((i) => i.id === item.id);
38 if (existing) {
39 existing.quantity += 1;
40 } else {
41 state.items.push({ ...item, quantity: 1 });
42 }
43 }),
44
45 removeItem: (id) =>
46 set((state) => {
47 state.items = state.items.filter((i) => i.id !== id);
48 }),
49
50 updateQuantity: (id, quantity) =>
51 set((state) => {
52 const item = state.items.find((i) => i.id === id);
53 if (item) {
54 if (quantity <= 0) {
55 state.items = state.items.filter((i) => i.id !== id);
56 } else {
57 item.quantity = quantity;
58 }
59 }
60 }),
61
62 clearCart: () => set({ items: [] }),
63 toggleCart: () =>
64 set((state) => {
65 state.isOpen = !state.isOpen;
66 }),
67
68 getTotal: () =>
69 get().items.reduce((sum, item) => sum + item.price * item.quantity, 0),
70
71 getItemCount: () =>
72 get().items.reduce((sum, item) => sum + item.quantity, 0),
73 })),
74 {
75 name: 'cart-storage',
76 storage: createJSONStorage(() => localStorage),
77 partialize: (state) => ({ items: state.items }),
78 }
79 )
80);
81
Hydration-Safe Component Pattern
typescript
1// components/CartButton.tsx
2'use client';
3
4import { useEffect, useState } from 'react';
5import { useCartStore } from '@/stores/cart-store';
6
7export function CartButton() {
8 const [mounted, setMounted] = useState(false);
9 const toggleCart = useCartStore((s) => s.toggleCart);
10 const itemCount = useCartStore((s) => s.getItemCount());
11
12 useEffect(() => setMounted(true), []);
13
14 return (
15 <button onClick={toggleCart} className="relative">
16 <ShoppingCartIcon />
17 {mounted && itemCount > 0 && (
18 <span className="absolute -top-2 -right-2 bg-red-500 text-white rounded-full w-5 h-5 text-xs flex items-center justify-center">
19 {itemCount}
20 </span>
21 )}
22 </button>
23 );
24}
25
The mounted check prevents hydration mismatches. The server renders the button without the count badge, then the client hydrates and shows the count from localStorage.
Zustand Store with Computed Selectors
typescript
1// stores/notifications-store.ts
2import { create } from 'zustand';
3import { subscribeWithSelector } from 'zustand/middleware';
4
5interface Notification {
6 id: string;
7 type: 'info' | 'success' | 'warning' | 'error';
8 title: string;
9 message: string;
10 timestamp: number;
11 read: boolean;
12 action?: { label: string; href: string };
13}
14
15interface NotificationState {
16 notifications: Notification[];
17 maxVisible: number;
18}
19
20interface NotificationActions {
21 addNotification: (notification: Omit<Notification, 'id' | 'timestamp' | 'read'>) => void;
22 markAsRead: (id: string) => void;
23 markAllAsRead: () => void;
24 dismiss: (id: string) => void;
25 clearAll: () => void;
26}
27
28export const useNotificationStore = create<NotificationState & NotificationActions>()(
29 subscribeWithSelector((set) => ({
30 notifications: [],
31 maxVisible: 5,
32
33 addNotification: (notification) =>
34 set((state) => ({
35 notifications: [
36 {
37 ...notification,
38 id: crypto.randomUUID(),
39 timestamp: Date.now(),
40 read: false,
41 },
42 ...state.notifications,
43 ].slice(0, 50), // Keep last 50
44 })),
45
46 markAsRead: (id) =>
47 set((state) => ({
48 notifications: state.notifications.map((n) =>
49 n.id === id ? { ...n, read: true } : n
50 ),
51 })),
52
53 markAllAsRead: () =>
54 set((state) => ({
55 notifications: state.notifications.map((n) => ({ ...n, read: true })),
56 })),
57
58 dismiss: (id) =>
59 set((state) => ({
60 notifications: state.notifications.filter((n) => n.id !== id),
61 })),
62
63 clearAll: () => set({ notifications: [] }),
64 }))
65);
66
67// Derived selectors — compute once, memoize automatically
68export const selectUnreadCount = (state: NotificationState) =>
69 state.notifications.filter((n) => !n.read).length;
70
71export const selectVisibleNotifications = (state: NotificationState & NotificationActions) =>
72 state.notifications.slice(0, state.maxVisible);
73
74// Subscribe to changes outside of React
75useNotificationStore.subscribe(
76 (state) => selectUnreadCount(state),
77 (unreadCount) => {
78 document.title = unreadCount > 0
79 ? `(${unreadCount}) My App`
80 : 'My App';
81 }
82);
83
Redux Toolkit for Complex Domains
Redux Toolkit earns its place in Next.js apps when you have deeply interconnected state with complex business logic — think collaborative editors, financial dashboards, or workflow builders.
Store Setup with Next.js Compatibility
typescript
1// stores/redux/store.ts
2import { configureStore } from '@reduxjs/toolkit';
3import { useDispatch, useSelector, useStore } from 'react-redux';
4import { workflowSlice } from './slices/workflow';
5import { collaborationSlice } from './slices/collaboration';
6import { historySlice } from './slices/history';
7import { workflowApi } from './api/workflow-api';
8
9export const makeStore = () =>
10 configureStore({
11 reducer: {
12 workflow: workflowSlice.reducer,
13 collaboration: collaborationSlice.reducer,
14 history: historySlice.reducer,
15 [workflowApi.reducerPath]: workflowApi.reducer,
16 },
17 middleware: (getDefault) =>
18 getDefault().concat(workflowApi.middleware),
19 });
20
21export type AppStore = ReturnType<typeof makeStore>;
22export type RootState = ReturnType<AppStore['getState']>;
23export type AppDispatch = AppStore['dispatch'];
24
25export const useAppDispatch = useDispatch.withTypes<AppDispatch>();
26export const useAppSelector = useSelector.withTypes<RootState>();
27export const useAppStore = useStore.withTypes<AppStore>();
28
Store Provider for Next.js App Router
typescript
1// stores/redux/StoreProvider.tsx
2'use client';
3
4import { useRef } from 'react';
5import { Provider } from 'react-redux';
6import { makeStore, AppStore } from './store';
7
8interface StoreProviderProps {
9 children: React.ReactNode;
10 initialState?: Partial<ReturnType<AppStore['getState']>>;
11}
12
13export function StoreProvider({ children, initialState }: StoreProviderProps) {
14 const storeRef = useRef<AppStore | null>(null);
15
16 if (!storeRef.current) {
17 storeRef.current = makeStore();
18
19 if (initialState) {
20 // Hydrate with server-fetched data
21 Object.entries(initialState).forEach(([key, value]) => {
22 if (value !== undefined) {
23 storeRef.current!.dispatch({
24 type: `${key}/hydrate`,
25 payload: value,
26 });
27 }
28 });
29 }
30 }
31
32 return <Provider store={storeRef.current}>{children}</Provider>;
33}
34
Workflow Builder Slice with Complex Logic
typescript
1// stores/redux/slices/workflow.ts
2import { createSlice, createAsyncThunk, PayloadAction } from '@reduxjs/toolkit';
3import type { RootState } from '../store';
4
5interface WorkflowNode {
6 id: string;
7 type: 'trigger' | 'action' | 'condition' | 'delay';
8 position: { x: number; y: number };
9 config: Record<string, unknown>;
10 connections: { targetId: string; label?: string }[];
11}
12
13interface WorkflowState {
14 nodes: Record<string, WorkflowNode>;
15 selectedNodeId: string | null;
16 isDirty: boolean;
17 lastSaved: number | null;
18 validationErrors: Record<string, string[]>;
19 executionStatus: 'idle' | 'running' | 'paused' | 'completed' | 'failed';
20}
21
22const initialState: WorkflowState = {
23 nodes: {},
24 selectedNodeId: null,
25 isDirty: false,
26 lastSaved: null,
27 validationErrors: {},
28 executionStatus: 'idle',
29};
30
31export const saveWorkflow = createAsyncThunk(
32 'workflow/save',
33 async (_, { getState }) => {
34 const state = getState() as RootState;
35 const nodes = Object.values(state.workflow.nodes);
36
37 const res = await fetch('/api/workflows/current', {
38 method: 'PUT',
39 headers: { 'Content-Type': 'application/json' },
40 body: JSON.stringify({ nodes }),
41 });
42
43 if (!res.ok) throw new Error('Save failed');
44 return res.json();
45 }
46);
47
48export const workflowSlice = createSlice({
49 name: 'workflow',
50 initialState,
51 reducers: {
52 hydrate: (_, action: PayloadAction<WorkflowState>) => action.payload,
53
54 addNode: (state, action: PayloadAction<Omit<WorkflowNode, 'connections'>>) => {
55 const node: WorkflowNode = { ...action.payload, connections: [] };
56 state.nodes[node.id] = node;
57 state.isDirty = true;
58 state.selectedNodeId = node.id;
59 },
60
61 moveNode: (state, action: PayloadAction<{ id: string; position: { x: number; y: number } }>) => {
62 const node = state.nodes[action.payload.id];
63 if (node) {
64 node.position = action.payload.position;
65 state.isDirty = true;
66 }
67 },
68
69 connectNodes: (
70 state,
71 action: PayloadAction<{ sourceId: string; targetId: string; label?: string }>
72 ) => {
73 const source = state.nodes[action.payload.sourceId];
74 if (!source) return;
75
76 // Prevent duplicate connections
77 const exists = source.connections.some(
78 (c) => c.targetId === action.payload.targetId
79 );
80 if (exists) return;
81
82 // Prevent self-connections
83 if (action.payload.sourceId === action.payload.targetId) return;
84
85 source.connections.push({
86 targetId: action.payload.targetId,
87 label: action.payload.label,
88 });
89 state.isDirty = true;
90 },
91
92 deleteNode: (state, action: PayloadAction<string>) => {
93 const nodeId = action.payload;
94 delete state.nodes[nodeId];
95
96 // Clean up connections referencing deleted node
97 Object.values(state.nodes).forEach((node) => {
98 node.connections = node.connections.filter((c) => c.targetId !== nodeId);
99 });
100
101 if (state.selectedNodeId === nodeId) {
102 state.selectedNodeId = null;
103 }
104 state.isDirty = true;
105 },
106
107 selectNode: (state, action: PayloadAction<string | null>) => {
108 state.selectedNodeId = action.payload;
109 },
110
111 validateWorkflow: (state) => {
112 const errors: Record<string, string[]> = {};
113
114 Object.values(state.nodes).forEach((node) => {
115 const nodeErrors: string[] = [];
116
117 if (node.type === 'trigger' && !node.config.event) {
118 nodeErrors.push('Trigger must have an event configured');
119 }
120
121 if (node.type === 'action' && !node.config.actionType) {
122 nodeErrors.push('Action type is required');
123 }
124
125 if (node.type === 'condition' && !node.config.expression) {
126 nodeErrors.push('Condition expression is required');
127 }
128
129 // Check for orphaned nodes (no incoming connections except triggers)
130 if (node.type !== 'trigger') {
131 const hasIncoming = Object.values(state.nodes).some((n) =>
132 n.connections.some((c) => c.targetId === node.id)
133 );
134 if (!hasIncoming) {
135 nodeErrors.push('Node is not connected to the workflow');
136 }
137 }
138
139 if (nodeErrors.length > 0) {
140 errors[node.id] = nodeErrors;
141 }
142 });
143
144 state.validationErrors = errors;
145 },
146 },
147 extraReducers: (builder) => {
148 builder
149 .addCase(saveWorkflow.fulfilled, (state) => {
150 state.isDirty = false;
151 state.lastSaved = Date.now();
152 })
153 .addCase(saveWorkflow.rejected, (state) => {
154 // Keep isDirty true so user knows save failed
155 });
156 },
157});
158
159export const {
160 addNode,
161 moveNode,
162 connectNodes,
163 deleteNode,
164 selectNode,
165 validateWorkflow,
166} = workflowSlice.actions;
167
168// Selectors
169export const selectAllNodes = (state: RootState) => Object.values(state.workflow.nodes);
170export const selectSelectedNode = (state: RootState) =>
171 state.workflow.selectedNodeId
172 ? state.workflow.nodes[state.workflow.selectedNodeId]
173 : null;
174export const selectIsDirty = (state: RootState) => state.workflow.isDirty;
175export const selectNodeErrors = (id: string) => (state: RootState) =>
176 state.workflow.validationErrors[id] ?? [];
177
RTK Query for API Layer
typescript
1// stores/redux/api/workflow-api.ts
2import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
3
4interface Workflow {
5 id: string;
6 name: string;
7 status: 'draft' | 'active' | 'paused';
8 nodesCount: number;
9 lastRun: string | null;
10 createdAt: string;
11}
12
13interface WorkflowExecution {
14 id: string;
15 workflowId: string;
16 status: 'running' | 'completed' | 'failed';
17 startedAt: string;
18 completedAt: string | null;
19 logs: { timestamp: string; message: string; level: string }[];
20}
21
22export const workflowApi = createApi({
23 reducerPath: 'workflowApi',
24 baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
25 tagTypes: ['Workflow', 'Execution'],
26 endpoints: (builder) => ({
27 getWorkflows: builder.query<Workflow[], void>({
28 query: () => '/workflows',
29 providesTags: (result) =>
30 result
31 ? [
32 ...result.map(({ id }) => ({ type: 'Workflow' as const, id })),
33 { type: 'Workflow', id: 'LIST' },
34 ]
35 : [{ type: 'Workflow', id: 'LIST' }],
36 }),
37
38 getWorkflow: builder.query<Workflow, string>({
39 query: (id) => `/workflows/${id}`,
40 providesTags: (_, __, id) => [{ type: 'Workflow', id }],
41 }),
42
43 executeWorkflow: builder.mutation<WorkflowExecution, string>({
44 query: (id) => ({
45 url: `/workflows/${id}/execute`,
46 method: 'POST',
47 }),
48 invalidatesTags: (_, __, id) => [
49 { type: 'Workflow', id },
50 { type: 'Execution', id: 'LIST' },
51 ],
52 }),
53
54 getExecutions: builder.query<WorkflowExecution[], string>({
55 query: (workflowId) => `/workflows/${workflowId}/executions`,
56 providesTags: [{ type: 'Execution', id: 'LIST' }],
57 }),
58
59 getExecutionLogs: builder.query<
60 WorkflowExecution['logs'],
61 { workflowId: string; executionId: string }
62 >({
63 query: ({ workflowId, executionId }) =>
64 `/workflows/${workflowId}/executions/${executionId}/logs`,
65 // Poll every 2 seconds while execution is running
66 }),
67 }),
68});
69
70export const {
71 useGetWorkflowsQuery,
72 useGetWorkflowQuery,
73 useExecuteWorkflowMutation,
74 useGetExecutionsQuery,
75 useGetExecutionLogsQuery,
76} = workflowApi;
77
Context API for Theme and Auth State
React Context still has valid uses in Next.js — primarily for state that changes infrequently and needs to be available throughout the component tree.
Authentication Context
typescript
1// contexts/auth-context.tsx
2'use client';
3
4import { createContext, useContext, useEffect, useState, useCallback } from 'react';
5
6interface User {
7 id: string;
8 email: string;
9 name: string;
10 avatar: string;
11 role: 'user' | 'admin';
12}
13
14interface AuthState {
15 user: User | null;
16 isLoading: boolean;
17 isAuthenticated: boolean;
18}
19
20interface AuthActions {
21 login: (email: string, password: string) => Promise<void>;
22 logout: () => Promise<void>;
23 refreshUser: () => Promise<void>;
24}
25
26const AuthContext = createContext<(AuthState & AuthActions) | null>(null);
27
28export function AuthProvider({ children }: { children: React.ReactNode }) {
29 const [state, setState] = useState<AuthState>({
30 user: null,
31 isLoading: true,
32 isAuthenticated: false,
33 });
34
35 const refreshUser = useCallback(async () => {
36 try {
37 const res = await fetch('/api/auth/me');
38 if (res.ok) {
39 const user = await res.json();
40 setState({ user, isLoading: false, isAuthenticated: true });
41 } else {
42 setState({ user: null, isLoading: false, isAuthenticated: false });
43 }
44 } catch {
45 setState({ user: null, isLoading: false, isAuthenticated: false });
46 }
47 }, []);
48
49 useEffect(() => {
50 refreshUser();
51 }, [refreshUser]);
52
53 const login = useCallback(
54 async (email: string, password: string) => {
55 const res = await fetch('/api/auth/login', {
56 method: 'POST',
57 headers: { 'Content-Type': 'application/json' },
58 body: JSON.stringify({ email, password }),
59 });
60
61 if (!res.ok) {
62 const data = await res.json();
63 throw new Error(data.message ?? 'Login failed');
64 }
65
66 await refreshUser();
67 },
68 [refreshUser]
69 );
70
71 const logout = useCallback(async () => {
72 await fetch('/api/auth/logout', { method: 'POST' });
73 setState({ user: null, isLoading: false, isAuthenticated: false });
74 }, []);
75
76 return (
77 <AuthContext.Provider value={{ ...state, login, logout, refreshUser }}>
78 {children}
79 </AuthContext.Provider>
80 );
81}
82
83export function useAuth() {
84 const context = useContext(AuthContext);
85 if (!context) throw new Error('useAuth must be used within AuthProvider');
86 return context;
87}
88
Composing Providers Without Nesting Hell
typescript
1// app/providers.tsx
2'use client';
3
4import { AuthProvider } from '@/contexts/auth-context';
5import { StoreProvider } from '@/stores/redux/StoreProvider';
6import { ThemeProvider } from '@/contexts/theme-context';
7
8function composeProviders(...providers: React.ComponentType<{ children: React.ReactNode }>[]) {
9 return function ComposedProviders({ children }: { children: React.ReactNode }) {
10 return providers.reduceRight(
11 (acc, Provider) => <Provider>{acc}</Provider>,
12 children
13 );
14 };
15}
16
17export const Providers = composeProviders(
18 ThemeProvider,
19 AuthProvider,
20 StoreProvider
21);
22
typescript
1// app/layout.tsx
2import { Providers } from './providers';
3
4export default function RootLayout({ children }: { children: React.ReactNode }) {
5 return (
6 <html lang="en">
7 <body>
8 <Providers>{children}</Providers>
9 </body>
10 </html>
11 );
12}
13
Decision Framework: Choosing the Right Tool
After building dozens of Next.js applications, here's the decision matrix we use:
| State Type | Solution | When |
|---|---|---|
| Server data | fetch + next/cache | Always start here |
| URL-representable | useSearchParams | Filters, pagination, tabs |
| Form state | useActionState | Server Action forms |
| Local component | useState / useReducer | Single component or small tree |
| Global UI | Zustand | Theme, cart, notifications, modals |
| Complex domain | Redux Toolkit | Workflow builders, collaborative editing |
| Auth/Config | React Context | Infrequent updates, wide availability |
The decision process:
- Can the server own this data? → Use
fetchwith cache tags - Should this survive in the URL? → Use search params
- Is this local to one component tree? → Use
useStateoruseReducer - Is this global UI state? → Use Zustand
- Is this complex domain state with many interacting pieces? → Use Redux Toolkit
Performance Benchmarks
We measured re-render counts on a product catalog page with 200 items, filters, and a cart:
1Approach | Re-renders on filter change | Bundle impact
2----------------------------|----------------------------|-------------
3URL state + Server Component| 0 (server re-render) | 0 KB
4useState (lifted) | 847 | 0 KB
5React Context | 312 | 0 KB
6Zustand (selector) | 12 | 1.1 KB
7Redux Toolkit (selector) | 12 | 11.2 KB
8
The URL state approach wins decisively — zero client re-renders because the server handles it. When you need client state, both Zustand and Redux perform identically with proper selectors, but Zustand's bundle cost is 10x smaller.
Conclusion
State management in Next.js is fundamentally different from state management in React SPAs. The server/client boundary isn't a limitation — it's an architectural advantage that eliminates entire categories of client-side state.
Start with the framework's built-in tools: fetch with cache tags for server state, search params for URL state, and useActionState for forms. These three cover the majority of state management needs in a typical Next.js application. Only reach for Zustand when you have genuinely global client state like a shopping cart or notification system. Reserve Redux Toolkit for complex domain models where centralized actions, middleware, and devtools provide real debugging value.
The best Next.js state management is the state management you don't write. Every piece of state you push to the server through Server Components or the URL through search params is state that doesn't need hydration safety, doesn't cause re-renders, and doesn't add to your bundle. Let the framework do the heavy lifting.