Split out from the original flat frontend-learning.md (moved to learning/archive/).
See also learning/frontend/01-routing.md (Server vs Client Components — the context this state
layer lives inside), learning/frontend/03-auth.md (the baseQueryWithReauth token-refresh queue),
learning/frontend/06-realtime.md (how Socket.IO events feed back into the RTK Query cache),
learning/frontend/08-performance-debugging.md, and the other learning/frontend/*.md files.
This file covers: Redux Toolkit slices for local UI state, RTK Query for server-state fetching
and caching (queries, mutations, lazy queries, the shared baseQueryWithReauth), and the general
scaling patterns used across the RTK Query API layer — splitting APIs by domain, centralising
error handling, environment variable rules, avoiding prop drilling, debouncing, and the
Socket.IO reconnection/re-join rule that also applies at the state layer.
9. State Management — Redux Toolkit
Redux Toolkit (RTK) is the official, modern way to use Redux. This project has two categories of Redux state:
Slices — local UI state
Slices hold state that doesn’t come from the API: who is logged in, the current event form values, canvas state, UI flags.
// src/app/provider/slices/user.ts
const authSlice = createSlice({
name: "auth",
initialState: { user: null, isAuthenticated: false },
reducers: {
setUser(state, action: PayloadAction<IUser | null>) {
state.user = action.payload; // Immer allows direct mutation
},
logout(state) {
state.user = null;
state.isAuthenticated = false;
},
},
});Slices in this project:
| Slice | Purpose |
|---|---|
user | Auth state: who is logged in, their role |
eventForm | Multi-step event creation form values |
location | User’s selected location |
canvas | Fabric.js canvas state for postcard editor |
ui | UI flags like hideHeader |
Using slice state in a component
"use client";
import { useSelector, useDispatch } from "react-redux";
import { RootState } from "@/app/provider/store";
import { logout } from "@/app/provider/slices/user";
function ProfileButton() {
const user = useSelector((state: RootState) => state.user.user);
const dispatch = useDispatch();
return (
<div>
<p>{user?.username}</p>
<button onClick={() => dispatch(logout())}>Log out</button>
</div>
);
}The store — wiring everything together
// src/app/provider/store.ts
export const store = configureStore({
reducer: {
user: authReducer,
eventForm: eventFormReducer,
[authApi.reducerPath]: authApi.reducer, // RTK Query APIs also go in the reducer
// ... all other APIs
},
middleware: (getDefaultMiddleware) =>
getDefaultMiddleware().concat(
authApi.middleware,
// ... all other API middlewares (required for caching, invalidation)
),
});The store is provided to the app through <Provider store={store}> inside ProviderWrapper, which wraps the entire app in the root layout.
10. Data Fetching — RTK Query
RTK Query is a data fetching and caching layer built into Redux Toolkit. It replaces useEffect + fetch + useState for API calls.
Defining an API
// src/app/provider/api/eventApi.ts
export const eventsApi = createApi({
reducerPath: "eventsApi", // key in the Redux store
baseQuery: baseQueryWithReauth, // all requests go through this
tagTypes: ["Events"], // for cache invalidation
endpoints: (builder) => ({
// Query = GET — reads data, caches it
getEvents: builder.query<EventsResponse, void>({
query: () => "/v1/events",
providesTags: ["Events"],
}),
// Mutation = POST/PUT/DELETE — writes data, can invalidate cache
createEvent: builder.mutation<Event, CreateEventBody>({
query: (body) => ({ url: "/v1/events", method: "POST", body }),
invalidatesTags: ["Events"], // clears the events cache after creating one
}),
}),
});
export const { useGetEventsQuery, useCreateEventMutation } = eventsApi;Using queries in components
function EventList() {
const { data, isLoading, isError, refetch } = useGetEventsQuery();
if (isLoading) return <Spinner />;
if (isError) return <ErrorMessage onRetry={refetch} />;
return <ul>{data?.data.map(e => <EventCard key={e.id} event={e} />)}</ul>;
}RTK Query automatically:
- Deduplicates identical requests (if 3 components call
useGetEventsQuery(), only 1 HTTP request goes out) - Caches results
- Refetches when the cache is invalidated
- Manages loading/error state
Using mutations
function CreateEventButton() {
const [createEvent, { isLoading }] = useCreateEventMutation();
const handleCreate = async () => {
try {
const newEvent = await createEvent({ name: "My Event" }).unwrap();
toast.success("Created!");
} catch (err: any) {
toast.error(err?.data?.message ?? "Something went wrong");
}
};
return <button onClick={handleCreate} disabled={isLoading}>Create</button>;
}.unwrap() throws on error instead of returning it — lets you use try/catch. (See learning/frontend/05-uploads-errors.md for the universal errorHandler() function most catch blocks in this project actually call.)
Lazy queries — fetch on demand
const [verifyPayment, { isLoading }] = useLazyVerifyOrganizerPaymentQuery();
// Called imperatively, not on mount
const result = await verifyPayment(paymentId).unwrap();Used in the payment verify page to poll manually instead of fetching on mount. (See learning/frontend/07-payments-games.md Part 13 for the full payment polling flow this lazy query is part of.)
The baseQueryWithReauth
Every RTK Query API in this project uses a shared baseQueryWithReauth instead of a plain fetchBaseQuery. It adds:
- Token attachment — reads
accessTokenfrom the cookie and addsAuthorization: Bearer <token>to every request - Token refresh — on a 401, automatically calls
/v1/auth/refresh, stores the new token, and retries the original request - Queue pattern — if multiple requests 401 at the same time, only one refresh happens; the rest wait
Request → prepareHeaders (attach token) → API → 401?
↓
isRefreshing?
Yes → queue the request, wait
No → call /refresh, update cookie,
flush queue, retry all
(See learning/frontend/03-auth.md for the full mechanics of this refresh queue, plus the PUBLIC_PATHS allowlist that prevents it from redirecting anonymous users to login on public pages.)
19. Scaling Patterns
Split RTK Query APIs by domain
Each API file in this project covers one domain (eventApi.ts, paymentApi.ts, messagingApi.ts). This keeps files manageable and allows independent cache invalidation. Never put everything in one giant api.ts.
Centralise error handling
All API errors flow through baseQueryWithReauth. Add global error handling there instead of duplicating try/catch everywhere:
// In baseQueryWithReauth — handle 403 globally
if (result.error?.status === 403) {
toast.error("You don't have permission to do that.");
}Environment variables
Next.js has two types:
| Variable | Accessible |
|---|---|
NEXT_PUBLIC_* | Browser + server. Baked into the client bundle at build time. |
| Everything else | Server only. Never exposed to the browser. |
// Safe to use in browser code
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
// Server-only (API routes, Server Components)
const secretKey = process.env.ERCASPAY_SECRET_KEY;Never put secrets in NEXT_PUBLIC_ variables — they’ll appear in the compiled JavaScript. (See learning/09-devops.md Part 38 for the equivalent backend-side environment variable dev/prod split rule.)
Avoid prop drilling with context or Redux
When state needs to travel more than 2-3 levels, put it in Redux or a React Context instead of threading it through props:
// Instead of: <A eventId={eventId}><B eventId={eventId}><C eventId={eventId} /></B></A>
// Use: useSelector or useContext inside C directlyDebounce user inputs
Heavy operations (search, map panning, canvas manipulation) should be debounced:
import { useDebouncedCallback } from "use-debounce";
const handleSearch = useDebouncedCallback((value: string) => {
setQuery(value);
}, 300); // wait 300ms after user stops typingThis project includes use-debounce — use it anywhere you’re calling APIs or doing expensive work on keystrokes.
Socket.IO reconnection
When a user’s network drops and reconnects, Socket.IO auto-reconnects the socket. But room membership is not preserved — you must re-join. Always put your socket.emit("join:*", ...) inside the effect that depends on isConnected, so it fires again after every reconnection. (See learning/frontend/06-realtime.md for the full, corrected event-driven version of this pattern — the naive isConnected-dependent effect described here has a real race condition that Part 36 there walks through and fixes.)
Quick Reference
Most-used RTK Query patterns
// Query (read)
const { data, isLoading, isError, refetch } = useGetSomethingQuery(arg);
// Lazy query (on demand)
const [trigger, { data, isLoading }] = useLazyGetSomethingQuery();
await trigger(arg).unwrap();
// Mutation (write)
const [mutate, { isLoading }] = useSomeMutation();
await mutate(body).unwrap();Most-used Redux patterns
const value = useSelector((state: RootState) => state.sliceName.field);
const dispatch = useDispatch();
dispatch(someAction(payload));20. Cache Invalidation with Tags — a Worked Example (Rewards)
Adding the “redeem your prize” page was a clean, minimal RTK Query slice. Two endpoints on the existing gamesApi:
// tagTypes now includes "Rewards"
getMyRewards: build.query<RewardsResponse, void>({
query: () => "/v1/my/rewards",
providesTags: ["Rewards"], // this query's data is "tagged" Rewards
}),
claimReward: build.mutation<ClaimRewardResponse, string>({
query: (rewardId) => ({ url: `/v1/rewards/${rewardId}/claim`, method: "POST" }),
invalidatesTags: ["Rewards"], // running this mutation marks Rewards stale
}),The whole point: after a successful claimReward, RTK Query automatically refetches getMyRewards — no manual refetch(), no local state juggling to flip isClaimed. The mutation invalidatesTags: ["Rewards"] and the query providesTags: ["Rewards"] are the two ends of the same string. The list re-renders with the reward now showing “Claimed” because the server is the source of truth and the cache was told it’s stale.
This is why you almost never keep a copy of server data in useState. The tag system is your cache-consistency mechanism.
void argument queries
getMyRewards takes no parameter (it’s scoped to the JWT’s user server-side), so its arg type is void and the hook is called with no argument:
const { data, isLoading } = useGetMyRewardsQuery(); // no argThe response envelope reaches the hook verbatim
The backend’s global ResponseInterceptor wraps every response as { success: true, data: <serviceReturn> }. RTK Query does not unwrap that — so the typed response is the envelope, and the component reads data?.data:
const rewards: Reward[] = data?.data ?? []; // data.data, not dataThis is the same reason the notifications page reaches data?.data?.data (envelope → { data, meta } → the array). Match your response TypeScript type to what the interceptor actually sends, not to what the service returns.
Duplicated display helpers across the client/server boundary
ordinal() and rewardTypeLabel() exist in both the backend (for the email) and this page (for the card). That duplication is acceptable — the two runtimes can’t share a module here, and the alternative (an API that returns pre-formatted display strings) would leak presentation concerns into the backend. Keep formatting on each side; share only data.
Optimistic updates need a server value to land on (2026-08-21)
The like button did this:
const wasLiked = liked;
setLiked(!wasLiked);
setLikeCount((c) => (wasLiked ? c - 1 : c + 1)); // optimistic guess
try {
const result = await toggleLikeMutation({ ... }).unwrap();
if (result?.currentLikes !== undefined) setLikeCount(result.currentLikes); // reconcile
} catch {
setLiked(wasLiked);
setLikeCount((c) => (wasLiked ? c + 1 : c - 1)); // roll back
}The structure is right — guess, reconcile, roll back on failure. It failed for
two reasons, and both are worth recognising as shapes rather than one-off bugs.
1. The reconcile step was dead code
The backend returned { liked } and nothing else, so result.currentLikes was
always undefined and the guard skipped the correction every single time. The
optimistic guess was the final state, permanently.
An optimistic update without a reconcile isn’t optimistic — it’s just a local
mutation that happens to fire a request. Worth grepping for: a !== undefined
guard around a field the API never actually sends looks like careful code and
behaves like no code at all.
2. The guess started from a wrong premise
The feed endpoints never returned isLiked, so every card rendered as un-liked:
const [optimisticLiked, setOptimisticLiked] = useState(postcard.isLiked ?? false);For a postcard the user had already liked, ?? false was wrong. Tapping the
heart therefore looked like a like to the client (c + 1) while the server
processed it as a toggle and removed the existing like. Client and server
moved in opposite directions on the same tap.
In postcard-viewer, where fresh data did supply isLiked: true against a
stale likeCount: 0, the same mismatch produced the actual reported symptom:
0 - 1 → a like count of -1 on screen, with no server value to correct it.
A toggle endpoint requires the client to know the current state. If the list
payload can’t tell you whether you’ve liked something, don’t render a toggle
against a guessed default — either have the API return the per-viewer state
(what we did: isLiked is now resolved in one batched query per page of
results) or send an explicit like/unlike intent instead of a toggle.
The defensive floor
Clamping is the cheap last line, not the fix:
setLikeCount((c) => Math.max(0, wasLiked ? c - 1 : c + 1));Worth having — a count should never render negative regardless of what the API
says — but note it only hides the symptom. The real repairs were server-side:
return currentLikes, and send isLiked with every card. Reach for the clamp
as well as, never instead of.
Software engineering
Infrastructure & security
Computer science
Hardware & engineering