nextjs-app-router

# Next.js App Router (Deep Workflow) App Router **changes** **mental** **models**: **where** **code** **runs**, **what** **is** **cached**, **and** **how** **HTML** **streams**. **Defaults** **differ** **from** **Pages** **Router**—**call** **that** **out** **explicitly**. ## When to Offer This Workflow **Trigger conditions:** - **New** **App** **Router** **project** **or** **migration** **from** **pages/** - **Confusion** **Server** **vs** **Client** **Components**; **hooks** **errors** - **Stale** **data**, **wrong** **cache**, **need** **ISR** **semantics** **Initial offer:** Use **six stages**: (1) route & layout model, (2) Server vs Client boundaries, (3) data fetching & cache, (4) revalidation & tags, (5) streaming & UX, (6) deployment & runtime. Confirm **Next** **version** **and** **hosting** **(Vercel** **self**, **etc.)**. --- ## Stage 1: Route & Layout Model **Goal:** **`app/`** **directory** **=** **nested** **layouts** **+** **col** **ocated** **routes**. ### Practices - **`layout.tsx`** **for** **shared** **UI** **and** **providers** **(client** **where** **needed)** - **`page.tsx`** **is** **leaf** **UI** **per** **segment** - **`loading.tsx`**, **`error.tsx`**, **`not-found`** **for** **UX** **boundaries** **Exit condition:** **URL** **tree** **matches** **folder** **tree** **mental** **model**. --- ## Stage 2: Server vs Client Components **Goal:** **Default** **Server** **Components**; **`use client`** **only** **where** **interactivity** **needs** **browser** **APIs** **or** **state**. ### Rules of thumb - **Data** **fetch** **on** **server** **by** **default** **(async** **components)** - **Leaf** **interactive** **islands** **as** **client** **components** - **Prop** **serialization**: **only** **JSON-serializable** **props** **across** **boundary** **Exit condition:** **List** **of** **client** **components** **and** **why**. --- ## Stage 3: Data Fetching & Cache **Goal:** `fetch` **cache** **semantics** **(force-cache** **vs** **no-store** **vs** **revalidate)** **explicit** **per** **call**. ### Practices - **Align** **with** **auth**: **no-store** **or** **request** **memoization** **patterns** **for** **user-specific** **data** - **Parallel** **fetch** **where** **possible** **to** **avoid** **waterfalls** **Exit condition:** **Per-route** **data** **dependency** **graph** **(simple** **diagram)**. --- ## Stage 4: Revalidation & Tags **Goal:** **Fresh** **when** **needed** **without** **DDOS** **origin**. ### Practices - **`revalidatePath`** / **`revalidateTag`** **from** **server** **actions** **or** **route** **handlers** - **Webhook-triggered** **revalidation** **for** **CMS** **Exit condition:** **Invalidation** **owner** **and** **trigger** **documented**. --- ## Stage 5: Streaming & UX **Goal:** **`Suspense`** **boundaries** **with** **meaningful** **fallbacks**; **a11y** **for** **loading**. ### Practices - **Avoid** **waterfall** **inside** **suspense** **trees** **(sequential** **awaits)** --- ## Stage 6: Deployment & Runtime **Goal:** **Node** **vs** **edge** **runtime** **per** **route** **segment** **when** **using** **edge**. ### Practices - **Edge** **cannot** **use** **all** **Node** **APIs**—**verify** **compat** - **ISR** **on** **serverless** **may** **need** **warming** **or** **cron** **revalidate** --- ## Final Review Checklist - [ ] Layouts and route segments match product IA - [ ] Server/Client split justified; props serializable - [ ] Fetch cache and auth story correct per route - [ ] Revalidation path defined for CMS/dynamic data - [ ] Streaming/suspense without accidental waterfalls - [ ] Runtime (edge vs node) matches dependencies ## Tips for Effective Guidance - **Refer** **to** **current** **Next.js** **docs** **for** **default** **fetch** **caching** **—** **defaults** **changed** **across** **versions**. - **Middleware** **for** **auth** **redirects** **—** **mind** **matcher** **performance**. - **Colocation** **of** **tests** **and** **Storybook** **for** **client** **components** **helps** **isolation**. ## Handling Deviations - **Pages** **Router** **legacy**: **map** **equivalents** **(getServerSideProps** **→** **async** **RSC)** **carefully**. - **Turbopack** **/** **Webpack** **—** **different** **perf** **profiles** **in** **dev**.