+ {/* Pokemon selector */}
+
+
+ Pick a Pokemon
+
+ Each selection triggers
+
+
+
+
+
+ {/* Pokemon card */}
+
+
+
+ Height: {data.height / 10}m · Weight: {data.weight / 10}kg
+
+
+
+
+
+
+
+
+ );
+}
diff --git a/src/features/react-query-demo/components/pokemon-skeleton.tsx b/src/features/react-query-demo/components/pokemon-skeleton.tsx
new file mode 100644
index 0000000..b26f091
--- /dev/null
+++ b/src/features/react-query-demo/components/pokemon-skeleton.tsx
@@ -0,0 +1,52 @@
+import { Card, CardHeader, CardContent, CardFooter } from '@/components/ui/card';
+
+export function PokemonSkeleton() {
+ return (
+ useSuspenseQuery — cached results are instant, new
+ fetches show the Suspense fallback.
+
+ {POKEMON_IDS.map((id) => (
+
+ ))}
+
+
+ {data.name}
+
+
+ {data.types.map(({ type }) => (
+
+ {type.name}
+
+ ))}
+
+
+ {/* eslint-disable-next-line @next/next/no-img-element */}
+ 
+
+
+ {data.stats.map((s) => (
+
+
+
+ ))}
+
+ {s.stat.name}
+ {s.base_stat}
+
+
+ + Data from PokeAPI · Prefetched on server, hydrated on client +
+
+ {/* Selector card skeleton */}
+
+
+
+
+
+
+
+
+
+ {/* Pokemon card skeleton */}
+
+
+
+
+
+
+
+
+
+
+ );
+}
diff --git a/src/features/react-query-demo/info-content.ts b/src/features/react-query-demo/info-content.ts
new file mode 100644
index 0000000..005f1fc
--- /dev/null
+++ b/src/features/react-query-demo/info-content.ts
@@ -0,0 +1,46 @@
+import type { InfobarContent } from '@/components/ui/infobar';
+
+export const reactQueryInfoContent: InfobarContent = {
+ title: 'React Query Pattern',
+ sections: [
+ {
+ title: 'Server Prefetch',
+ description:
+ 'Data is prefetched on the server using getQueryClient().prefetchQuery(). The dehydrated state is passed to HydrationBoundary so the client starts with cached data — no loading spinners on first load.',
+ links: [
+ {
+ title: 'TanStack Query SSR Docs',
+ url: 'https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr'
+ }
+ ]
+ },
+ {
+ title: 'Query Options',
+ description:
+ 'Query keys and fetch functions are defined in a shared queryOptions() object. This is reused across server prefetch and client hooks, keeping them in sync.',
+ links: [
+ {
+ title: 'queryOptions API',
+ url: 'https://tanstack.com/query/latest/docs/framework/react/reference/queryOptions'
+ }
+ ]
+ },
+ {
+ title: 'Suspense Query',
+ description:
+ 'The client uses useSuspenseQuery() which integrates with React Suspense. Combined with server prefetch, data is available immediately — Suspense only shows the fallback on subsequent navigations if the cache is stale.',
+ links: []
+ },
+ {
+ title: 'Optimistic Mutations',
+ description:
+ 'Mutations use onMutate to optimistically update the cache before the request completes. On error, the previous state is rolled back. On settle, the query is invalidated to refetch fresh data.',
+ links: [
+ {
+ title: 'Optimistic Updates Guide',
+ url: 'https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates'
+ }
+ ]
+ }
+ ]
+};
diff --git a/src/features/users/api/mutations.ts b/src/features/users/api/mutations.ts
new file mode 100644
index 0000000..3ea82ac
--- /dev/null
+++ b/src/features/users/api/mutations.ts
@@ -0,0 +1,27 @@
+import { mutationOptions } from '@tanstack/react-query';
+import { getQueryClient } from '@/lib/query-client';
+import { createUser, updateUser, deleteUser } from './service';
+import { userKeys } from './queries';
+import type { UserMutationPayload } from './types';
+
+export const createUserMutation = mutationOptions({
+ mutationFn: (data: UserMutationPayload) => createUser(data),
+ onSuccess: () => {
+ getQueryClient().invalidateQueries({ queryKey: userKeys.all });
+ }
+});
+
+export const updateUserMutation = mutationOptions({
+ mutationFn: ({ id, values }: { id: number; values: UserMutationPayload }) =>
+ updateUser(id, values),
+ onSuccess: () => {
+ getQueryClient().invalidateQueries({ queryKey: userKeys.all });
+ }
+});
+
+export const deleteUserMutation = mutationOptions({
+ mutationFn: (id: number) => deleteUser(id),
+ onSuccess: () => {
+ getQueryClient().invalidateQueries({ queryKey: userKeys.all });
+ }
+});
diff --git a/src/features/users/api/queries.ts b/src/features/users/api/queries.ts
new file mode 100644
index 0000000..e76c2da
--- /dev/null
+++ b/src/features/users/api/queries.ts
@@ -0,0 +1,17 @@
+import { queryOptions } from '@tanstack/react-query';
+import { getUsers } from './service';
+import type { User, UserFilters } from './types';
+
+export type { User };
+
+export const userKeys = {
+ all: ['users'] as const,
+ list: (filters: UserFilters) => [...userKeys.all, 'list', filters] as const,
+ detail: (id: number) => [...userKeys.all, 'detail', id] as const
+};
+
+export const usersQueryOptions = (filters: UserFilters) =>
+ queryOptions({
+ queryKey: userKeys.list(filters),
+ queryFn: () => getUsers(filters)
+ });
diff --git a/src/features/users/api/service.ts b/src/features/users/api/service.ts
new file mode 100644
index 0000000..c938e18
--- /dev/null
+++ b/src/features/users/api/service.ts
@@ -0,0 +1,47 @@
+// ============================================================
+// User Service — Data Access Layer
+// ============================================================
+// This is the ONLY file you modify when connecting to your backend.
+// Queries (queries.ts) and components import from here — they never change.
+//
+// Pick your pattern and replace the function bodies below:
+//
+// 1. Server Actions + ORM (Prisma / Drizzle / Supabase)
+// → Add 'use server' at the top of this file
+// → Call your ORM directly in each function
+//
+// 2. Route Handlers + ORM
+// → import { apiClient } from '@/lib/api-client'
+// → return apiClient
+ {Array.from({ length: 10 }).map((_, i) => (
+
+ ))}
+
+
+
+
+
+
+
+
+
+
+ {Array.from({ length: 6 }).map((_, i) => (
+
+
+
+ ))}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {row.original.first_name} {row.original.last_name}
+
+ {row.original.email}
+
+ ),
+ meta: {
+ label: 'Name',
+ placeholder: 'Search users...',
+ variant: 'text' as const,
+ icon: Icons.text
+ },
+ enableColumnFilter: true
+ },
+ {
+ accessorKey: 'phone',
+ header: 'PHONE'
+ },
+ {
+ id: 'role',
+ accessorKey: 'role',
+ enableSorting: false,
+ header: ({ column }: { column: Column
+
+
+
+
+ );
+}
diff --git a/src/features/users/components/users-table/options.tsx b/src/features/users/components/users-table/options.tsx
new file mode 100644
index 0000000..f539062
--- /dev/null
+++ b/src/features/users/components/users-table/options.tsx
@@ -0,0 +1,8 @@
+export const ROLE_OPTIONS = [
+ { value: 'Developer', label: 'Developer' },
+ { value: 'Designer', label: 'Designer' },
+ { value: 'Manager', label: 'Manager' },
+ { value: 'QA', label: 'QA' },
+ { value: 'DevOps', label: 'DevOps' },
+ { value: 'Product Owner', label: 'Product Owner' }
+];
diff --git a/src/features/users/info-content.ts b/src/features/users/info-content.ts
new file mode 100644
index 0000000..5df1253
--- /dev/null
+++ b/src/features/users/info-content.ts
@@ -0,0 +1,41 @@
+import type { InfobarContent } from '@/components/ui/infobar';
+
+export const usersInfoContent: InfobarContent = {
+ title: 'Users — React Query + nuqs Pattern',
+ sections: [
+ {
+ title: 'Overview',
+ description:
+ 'This page demonstrates client-side data fetching with React Query combined with nuqs URL search params — as an alternative to the Products page which uses server-side RSC fetching. Both patterns use the same DataTable, useDataTable hook, and nuqs URL state.',
+ links: [
+ {
+ title: 'TanStack Query SSR Docs',
+ url: 'https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr'
+ }
+ ]
+ },
+ {
+ title: 'Server Prefetch + Client Hydration',
+ description:
+ 'The server component reads search params via searchParamsCache, builds filters, and calls queryClient.prefetchQuery(). The dehydrated state is passed to HydrationBoundary so the client starts with cached data. The client component reads the same search params via useQueryState and calls useSuspenseQuery with matching filters.',
+ links: []
+ },
+ {
+ title: 'URL State with nuqs',
+ description:
+ 'Pagination, search, and role filters are synced to the URL via nuqs. The useDataTable hook manages the TanStack Table state and debounces filter changes before updating the URL. When the URL changes, React Query automatically refetches because the query key includes the filters.',
+ links: [
+ {
+ title: 'nuqs Documentation',
+ url: 'https://nuqs.47ng.com'
+ }
+ ]
+ },
+ {
+ title: 'Products vs Users Pattern',
+ description:
+ 'Products: searchParams → RSC fetch → pass data as props to client table. Users: searchParams → server prefetch → HydrationBoundary → client useSuspenseQuery. The Users pattern enables background refetching, cache sharing across components, and optimistic mutations.',
+ links: []
+ }
+ ]
+};
diff --git a/src/features/users/schemas/user.ts b/src/features/users/schemas/user.ts
new file mode 100644
index 0000000..1086f5f
--- /dev/null
+++ b/src/features/users/schemas/user.ts
@@ -0,0 +1,12 @@
+import * as z from 'zod';
+
+export const userSchema = z.object({
+ first_name: z.string().min(2, 'First name must be at least 2 characters'),
+ last_name: z.string().min(2, 'Last name must be at least 2 characters'),
+ email: z.string().email('Please enter a valid email'),
+ phone: z.string().min(1, 'Phone number is required'),
+ role: z.string().min(1, 'Please select a role'),
+ status: z.string().min(1, 'Please select a status')
+});
+
+export type UserFormValues = z.infer