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.