Frontend skills

React + Next.js + Tailwind

Build production frontends that are fast by default and easy to change.

Core Mental Model

In Next.js App Router, every file is a Server Component until you opt out. Code only runs on the client when it has to (interactivity, browser APIs, hooks). Data is fetched where it's used (server-side, no API hop). Static, cached, and dynamic content coexist on the same page.

Before you write a component, answer four questions:

digraph where_runs {
    rankdir=LR;
    "Needs useState/useEffect/event handlers/browser API?" [shape=diamond];
    "Mutation (form submit, write)?" [shape=diamond];
    "External clients/webhooks consume it?" [shape=diamond];
    "Server Component (default)" [shape=box];
    "Client Component ('use client')" [shape=box];
    "Server Action ('use server')" [shape=box];
    "Route Handler (route.ts)" [shape=box];

    "Needs useState/useEffect/event handlers/browser API?" -> "Client Component ('use client')" [label="yes"];
    "Needs useState/useEffect/event handlers/browser API?" -> "Mutation (form submit, write)?" [label="no"];
    "Mutation (form submit, write)?" -> "Server Action ('use server')" [label="yes"];
    "Mutation (form submit, write)?" -> "External clients/webhooks consume it?" [label="no"];
    "External clients/webhooks consume it?" -> "Route Handler (route.ts)" [label="yes"];
    "External clients/webhooks consume it?" -> "Server Component (default)" [label="no"];
}

Top-Impact Rules (CRITICAL)

These are the rules whose violation costs the most. Treat them as defaults; deviate only with a stated reason.

#	Rule	Why it matters
1	No export const dynamic = 'force-dynamic' on Next.js 16+. Use 'use cache' for cacheable async work, <Suspense> for live data. (Import cacheLife/cacheTag from next/cache — alias from unstable_* if your version still ships them under that prefix.)	Cache Components let static/cached/dynamic coexist in one route. force-dynamic blocks every optimization.
2	Parallelize independent awaits with Promise.all — never serial await for unrelated work.	2–10× latency reduction on multi-fetch routes.
3	Configure optimizePackageImports in next.config.ts for any icon/UI library you import (lucide-react, @mui/*, @radix-ui/*, date-fns, etc.).	Barrel imports load 1,500–10,000 modules; 200–800 ms cold start cost.
4	Use next/link for internal navigation, next/image for every image, next/font for every font. Never raw <a href="/...">, <img>, or <link rel="stylesheet"> font URLs.	Lose prefetching, layout shift, font swapping.
5	Serialize props that cross the Server→Client boundary. Dates become ISO strings, Maps/Sets become arrays/objects, no functions (except Server Actions).	Class methods are stripped, Dates silently coerce to strings, then crash on .getFullYear().
6	No async Client Components. Fetch data in a Server parent and pass plain props down.	Async client components throw at runtime.
7	Wrap dynamic streaming work in <Suspense> with a real skeleton fallback. Add loading.tsx at the segment level for the route shell.	Streaming requires Suspense; the skeleton is the UX.
8	Prefer composition over boolean props. <Modal isHeader isFooter isDismissible> → <Modal.Frame><Modal.Header/>…, or distinct <ChannelComposer/> / <ThreadComposer/> variants.	Booleans multiply state combinatorially; compound components stay linear.
9	Don't try/catch redirect(), notFound(), forbidden(), or unauthorized(). They throw on purpose — let them through, or unstable_rethrow(error) in a catch.	Catching them silently breaks navigation.
10	Tailwind: pair every color with its dark: variant. Use semantic tokens via CSS variables for theming. Conditional classes via clsx/cn, not string templates.	Half-dark UIs leak white flashes. Strings with conditionals are unreadable.

What Goes Where

You want to…	Use
Read data for a page	Server Component — await db.… directly, no API
Cache an expensive read for the route	'use cache' + cacheLife() + cacheTag()
Handle a form submit / write	Server Action ('use server' file, pass to <form action={…}>)
Build a REST API for mobile / webhooks	Route Handler (app/api/.../route.ts)
Client-side fetch with deduplication	SWR (or TanStack Query) inside a Client Component
Run code once per request, deduped	react.cache()
Run code once per app load	Module-level let cached; export function get() { return cached ??= … }
Add interactivity to a single leaf	Mark only that leaf 'use client' — keep the page server

Deep References

Skim these when working in the relevant area. Each is dense reference material, not narrative.

• references/nextjs.md — Next.js 16 Cache Components, RSC boundaries, async params/cookies, file conventions, data patterns, error handling, image/font, scripts, parallel routes.
• references/react-performance.md — Eliminating waterfalls, bundle-size traps, server-side caching (react.cache, LRU, hoist static I/O), re-render optimization, advanced patterns.
• references/composition.md — Compound components, lift-state-into-provider, explicit variants, children over render props, React 19's use() replacing forwardRef.
• references/tailwind.md — Design tokens via CSS variables, dark mode discipline, clsx/cn/tailwind-merge, when to extract components vs. when to repeat utilities, responsive/state variants.
• references/design-principles.md — Refactoring UI school: hierarchy, whitespace, color, depth, polish. Read when the UI works but feels generic or undesigned.
• references/ui-patterns.md — Catalog of standard UI patterns (shells, navigation, forms, tables, modals, toasts, etc.) with composition + accessibility shape for each.
• references/common-mistakes.md — Before/after for the failures that show up most often, with diagnosis.

Common Mistakes — Quick Hits

Mistake	Fix
export const dynamic = 'force-dynamic' everywhere	Remove. Use 'use cache' for cacheable, <Suspense> for live, on Next.js 16+.
import { Icon } from 'lucide-react' with no optimizePackageImports	Add it to next.config.ts. Or import from the package's deep path.
<a href="/posts/[id]"> for internal routes	<Link href={/posts/${id}}> — restores prefetch + client nav.
<img src="...">	<Image src=… alt=… width height /> or fill + sizes.
'use client' at the top of the page	Push it down to the smallest interactive leaf. Keep parents server.
new Date(...) passed as a prop to a Client Component	.toISOString() server-side, re-parse on the client.
5 booleans on one component	Split into compound (X.Root, X.Item) or distinct variants.
Inline className={isActive ? "..." : "..."} strings repeated 6 times	Extract a variant helper (cva) or a component.
notFound() mentioned in a comment but not called	Call it. It throws and renders the closest not-found.tsx.
One huge Promise.all blocking the entire page	Wrap slow parts in <Suspense> so the rest streams.

Red Flags — Stop and Reconsider

• You're about to add the 3rd boolean prop. → Switch to composition.
• You wrote await twice in a row on unrelated values. → Promise.all.
• You typed 'use client' to fix an error you don't understand. → Find the real cause (often: trying to await in a client component, or pass a function from server).
• You're caching everything force-dynamic or nothing at all. → Pick what's cacheable per-component with 'use cache'.
• You're writing your own image lazy-loader / route prefetch / font CSS. → next/image / next/link / next/font already do it.
• A class instance, Date, Map, or function is on the props edge of a Client Component. → Serialize at the boundary.

When NOT to Apply

• Pure SPA (Vite + React, no SSR) — RSC and 'use cache' rules don't apply; React performance rules and Tailwind rules still do.
• Pages router (legacy Next.js) — file conventions differ; data-patterns and component patterns still apply.
• Outside React — only the broad principles (parallelize async, design tokens) carry over.