oakoss Frontend Builder
Overview
Builds maintainable, performant React and Next.js frontends using a server-first architecture. Covers component design, state management, data fetching, forms, styling, and performance optimization. Not for backend API design, database schema, or deployment infrastructure.
Quick Reference
| Pattern | Approach | Key Points |
|---|---|---|
| Framework | Next.js App Router (default), React + Vite (SPAs) | Server-first rendering, file-based routing |
| Components | Page, Feature, UI, Layout types | Single responsibility, typed props, composition |
| Server vs Client | Server Components default, 'use client' at leaf nodes |
Push interactivity to edges of component tree |
| State (local) | useState, props, lift to parent |
Keep state close to where it is consumed |
| State (global) | Context API (theme, auth), Zustand (complex) | Avoid Context for frequently changing values |
| Data fetching | Server Components (server), TanStack Query (client) | Server Actions for mutations, revalidatePath for cache |
| Forms | React Hook Form + Zod, or Server Actions + useActionState |
Schema validation, optimistic updates with useOptimistic |
| Styling | Tailwind CSS v4 + shadcn/ui | CSS-first config with @theme, OKLCH colors |
| Performance | Suspense streaming, code splitting, memoization | React.lazy(), next/dynamic, selective memo() |
| Error handling | Error boundaries, error.tsx per route |
Wrap feature sections, not individual components |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
Adding 'use client' to every component |
Default to Server Components; add 'use client' only for interactivity |
| Giant multi-responsibility component | Break into focused sub-components with single purposes |
| Placing all state at the top of the component tree | Keep state as close to where it is consumed as possible |
Using useEffect to compute derived data |
Use useMemo for derived values; reserve useEffect for side effects |
| Missing error boundaries around feature sections | Wrap feature areas with error boundaries to prevent full-page crashes |
| Creating API routes for simple mutations | Use Server Actions with 'use server' for form submissions and mutations |
| Passing non-serializable props to Client Components | Props crossing server/client boundary must be serializable (no functions, classes) |
Using tailwind.config.js with Tailwind v4 |
Use CSS-first configuration with @theme directive in CSS file |
| Fetching data in Client Components when Server Components suffice | Fetch in Server Components by default; use TanStack Query only when client-side caching is needed |
Delegation
When building frontends, delegate to specialized skills:
react-patterns-- React hooks, rendering patterns, and performance optimizationnextjs-- Next.js routing, middleware, and deployment configurationtanstack-query-- Client-side data fetching, caching, and mutationstanstack-form-- Complex form handling and field-level validationtailwind-- Tailwind CSS utility patterns and responsive designdesign-system-- Token hierarchy and component architectureperformance-optimizer-- Profiling, bundle analysis, and Core Web Vitals
References
- Component Architecture -- Component types, folder structure, TypeScript patterns, and composition
- Server Components -- Server/client boundary, Server Actions, Suspense streaming, and data flow
- State Management -- useState, Context API, Zustand, and URL state patterns
- Data Fetching -- TanStack Query, Server Components data, and cache revalidation
- Forms and Validation -- React Hook Form, Zod schemas, Server Actions, and useActionState
- Styling -- Tailwind CSS v4, shadcn/ui, CSS-first config, and responsive patterns
- Performance and Errors -- Memoization, code splitting, Suspense streaming, and error boundaries