# React Nextjs Patterns > Use this skill when the agent is implementing frontend code in Next.js projects, reviewing React or Next.js pull requests, onboarding to App Router conventions, or designing a frontend architecture that needs canonical React/Next.js patterns — for canonical React and Next.js conventions covering Next.js App Router routing and rendering, React Server Components vs Client Components boundary, TypeScript strict-mode discipline, Tailwind CSS and shadcn/ui styling, React Query and Server Actions data fetching, Core Web Vitals performance optimization, WCAG 2.2 accessibility, Next.js metadata API and structured data for SEO, unit testing with Vitest and React Testing Library, and end-to-end testing with Playwright. - Skill: `avav25/react-nextjs-patterns` (Agent Skill) - Install (CLI): `npx skillmds@latest add avav25/react-nextjs-patterns` - Raw SKILL.md: https://api.skillmd.com/api/skills/avav25/react-nextjs-patterns/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: avav25 (https://skillmd.com/u/avav25) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/avav25/react-nextjs-patterns --- # React + Next.js Patterns Knowledge layer for the `frontend-engineer` agent and any other agent or skill that needs canonical React and Next.js conventions. Auto-loaded via the `skills:` frontmatter on `frontend-engineer`. Read this when authoring, reviewing, or onboarding to Next.js App Router code — it codifies routing, RSC vs Client Component boundaries, TypeScript discipline, styling, data fetching, performance, accessibility, SEO, and testing patterns used across the project. ## Project Architecture (Next.js App Router) - Use the `app/` directory with file-based routing: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx` - Group related routes with `(group)` folders — no URL impact, clean organization - Use `route.ts` for API endpoints (GET, POST, PUT, DELETE, PATCH handlers) - Dynamic routes: `[param]` for single, `[...param]` for catch-all, `[[...param]]` for optional catch-all - Parallel routes (`@slot`) and intercepting routes (`(.)`, `(..)`) for modals and complex layouts - `middleware.ts` at project root for auth guards, redirects, headers, i18n ## React Server Components Decision tree — Server Component by default; switch to Client Component only when one of the following is required: - `useState`, `useReducer`, or any other React state hook - `useEffect` or other browser-lifecycle hooks - Event handlers (`onClick`, `onChange`, etc.) - Browser APIs (`window`, `document`, `localStorage`, `IntersectionObserver`) - Third-party libraries that depend on the above Rendering rules: - **Server Components**: default. Async data fetching, zero client JS, direct database/API access - **Client Components**: `'use client'` directive at the narrowest boundary — push it down to leaf components, never wrap entire pages - **Streaming**: use `loading.tsx` and `` to progressively render UI. Wrap slow data-dependent sections in Suspense boundaries - **Server Actions**: `'use server'` for form mutations and data writes. Validate all inputs with Zod. Use `revalidatePath()` / `revalidateTag()` after mutations - **Static vs Dynamic**: prefer static generation. Use `dynamic = 'force-dynamic'` or `revalidate` only when data must be fresh - **Hybrid pattern**: server parent fetches data, passes serializable props to a client child that needs interactivity ## TypeScript Patterns - Enable `strict: true`, `noUncheckedIndexedAccess: true` in `tsconfig.json` - No `any` — use `unknown`, strict generics, or explicit types - Define explicit return types for functions and components - Use discriminated unions for state machines and API responses - Prefer `interface` for object shapes, `type` for unions and intersections - Use the `satisfies` operator for type-safe configuration objects - Zod for runtime validation of external data (API responses, form inputs, URL params, Server Action inputs) - Group imports: `react` → `next` → third-party → `@/` local → relative ## React Component Patterns - Functional components only — no class components - Destructure props with a TypeScript interface - Use `forwardRef` when wrapping native elements or building design-system components - Composition over configuration: use `children`, render props, or slots instead of complex prop APIs - Co-locate component, types, and test in the same directory State management: - Local state: `useState` for simple values, `useReducer` for complex state logic - URL state: `useSearchParams`, `usePathname`, `useRouter` from `next/navigation` - Server state: React Query (`@tanstack/react-query`) with `useQuery`, `useMutation`, `useInfiniteQuery` - Global state: React Context for theme/auth. Avoid Context for frequently changing data — use React Query or Zustand - Form state: React Hook Form + Zod resolver for complex forms; Server Actions with `useActionState` for simple forms Hooks: - Custom hooks: prefix with `use`, single responsibility, return typed values - Never call hooks conditionally - Cleanup effects: always return a cleanup function in `useEffect` when subscribing to external resources - Prefer `useMemo`/`useCallback` only when profiling shows a measurable benefit — do not optimize prematurely ## Styling (Tailwind + shadcn/ui) - **Tailwind CSS**: utility-first. Use `cn()` helper (from `clsx` + `tailwind-merge`) for conditional classes. No inline styles. - **shadcn/ui**: default component library. Customize via Tailwind theme, not component internals - **Responsive**: mobile-first breakpoints (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`) - **Dark mode**: `class` strategy with `next-themes`. Design for both light and dark from the start - **Design tokens**: define colors, spacing, typography in `tailwind.config.ts` or CSS variables - **Animations**: prefer CSS transitions and `tailwindcss-animate`. Use Framer Motion only for complex choreography ## Data Fetching (React Query + Server Actions) - **Server Components**: `fetch()` with built-in Next.js caching and revalidation, or direct DB/ORM calls - **Route Handlers**: `app/api/**/route.ts` — use for webhook endpoints, third-party integrations, client-side API calls - **React Query**: wrap app in `QueryClientProvider`. Place query hooks in `hooks/` directory. Use query key factories: `['entity', params]` - **Server Actions**: for mutations (create, update, delete). Validate with Zod. Return typed result objects, not raw data. Use `revalidatePath` / `revalidateTag` to invalidate cache - **Error handling**: use `error.tsx` boundaries. Return structured errors from API routes (`{ error: string, code: number }`) - **Loading states**: `loading.tsx` for route-level, `` for component-level - **No data fetching in Client Components**: fetch in Server Components or Route Handlers; pass data down as serializable props ## Performance (Core Web Vitals) - **LCP** (Largest Contentful Paint): optimize hero images with `next/image` `priority` prop. Preload critical fonts via `next/font` - **INP** (Interaction to Next Paint): keep Client Components small. Defer non-critical JS with `next/dynamic` + `ssr: false` - **CLS** (Cumulative Layout Shift): reserve space for dynamic content. Set explicit image dimensions — `next/image` with `width`/`height` or `fill` Optimization checklist: - Minimize `'use client'` surface — push it down to leaf components - `next/dynamic` for heavy components not needed on initial render - `React.lazy` + `Suspense` for code splitting within Client Components - Images: `next/image` with responsive `sizes`, WebP/AVIF formats, `placeholder="blur"` - Bundle analysis: `@next/bundle-analyzer` to identify large dependencies - Prefetch: `` prefetches by default in viewport. Disable with `prefetch={false}` for low-priority links ## Accessibility (WCAG 2.2 AA) - Semantic HTML: `

`, `