CLAUDE.md

This is a Next.js 16 + shadcn/ui admin dashboard starter kit.

Key References

AGENTS.md — Full project overview, tech stack, structure, conventions, data fetching patterns, deployment
docs/forms.md — Form system: TanStack Form + Zod, composable fields, validation, multi-step, sheet/dialog forms
docs/themes.md — Theme system: OKLCH colors, adding themes, font config
docs/nav-rbac.md — Navigation RBAC: access control, Clerk integration
docs/clerk_setup.md — Clerk auth setup: organizations, billing, environment variables

React Query for all data fetching — void prefetchQuery() on server + useSuspenseQuery on client (standard TanStack pattern), useMutation for forms, HydrationBoundary + dehydrate for hydration, <Suspense fallback> for streaming
API layer per feature — api/types.ts → api/service.ts → api/queries.ts; queries use key factories (entityKeys.all/list/detail); components import from service and queries, never from mock APIs directly
nuqs for URL search params — searchParamsCache on server, useQueryStates on client, use getSortingStateParser for sort (same parser as useDataTable)
Icons — only import from @/components/icons, never from @tabler/icons-react directly
Forms — use useAppForm + useFormFields<T>() from @/components/ui/tanstack-form
Page headers — use PageContainer props (pageTitle, pageDescription, pageHeaderAction), never import <Heading> manually
Formatting — single quotes, JSX single quotes, no trailing comma, 2-space indent