Files
skills/public/frontend-nextjs-app-router.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

759 lines
30 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>frontend-nextjs-app-router</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/frontend-nextjs-app-router.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/frontend-nextjs-app-router">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/frontend-nextjs-app-router.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>frontend-nextjs-app-router</h1><p class="lede">Building Next.js 13+ applications</p><h1>Next.js App Router</h1>
<p><strong>Scope</strong>: App Router conventions, layouts, loading/error states, Server vs Client Components <strong>Lines</strong>: ~310 <strong>Last Updated</strong>: 2025-10-18</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Building Next.js 13+ applications</li><li>Working with App Router (app directory)</li><li>Deciding between Server and Client Components</li><li>Implementing layouts and nested routes</li><li>Handling loading and error states</li><li>Using Server Actions</li><li>Optimizing data fetching</li></ul>
<h2>Core Concepts</h2>
<h3>App Router vs Pages Router</h3>
<p><strong>Pages Router</strong> (Legacy):</p>
<pre><code>pages/
index.tsx # /
about.tsx # /about
blog/
[slug].tsx # /blog/:slug</code></pre>
<p><strong>App Router</strong> (New, recommended):</p>
<pre><code>app/
page.tsx # /
about/
page.tsx # /about
blog/
[slug]/
page.tsx # /blog/:slug</code></pre>
<p><strong>Key differences</strong>:</p>
<ul><li>File-based routing with folders (not files)</li><li>Server Components by default</li><li>Built-in layouts, loading, error states</li><li>Nested layouts and parallel routes</li><li>Server Actions for mutations</li></ul>
<hr>
<h2>File Conventions</h2>
<h3>Core Files</h3>
<pre><code>app/
layout.tsx # Root layout (required)
page.tsx # Route page
loading.tsx # Loading UI (Suspense boundary)
error.tsx # Error UI (Error boundary)
not-found.tsx # 404 UI
template.tsx # Re-rendered layout
route.ts # API route handler</code></pre>
<h3>Root Layout (Required)</h3>
<pre><code class="lang-tsx">// app/layout.tsx
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
&lt;html lang=&quot;en&quot;&gt;
&lt;body&gt;{children}&lt;/body&gt;
&lt;/html&gt;
);
}</code></pre>
<p><strong>Must include</strong>:</p>
<ul><li><code>&lt;html&gt;</code> and <code>&lt;body&gt;</code> tags</li><li>Root layout wraps entire app</li><li>Cannot be Client Component</li></ul>
<h3>Page Component</h3>
<pre><code class="lang-tsx">// app/page.tsx
export default function HomePage() {
return &lt;h1&gt;Home Page&lt;/h1&gt;;
}</code></pre>
<p><strong>Each route requires <code>page.tsx</code></strong> to be accessible.</p>
<h3>Loading Component</h3>
<pre><code class="lang-tsx">// app/dashboard/loading.tsx
export default function Loading() {
return &lt;div&gt;Loading dashboard...&lt;/div&gt;;
}</code></pre>
<p><strong>Automatic Suspense boundary</strong> - wraps page in <code>&lt;Suspense&gt;</code>.</p>
<h3>Error Component</h3>
<pre><code class="lang-tsx">// app/dashboard/error.tsx
&#x27;use client&#x27;; // Must be Client Component
export default function Error({
error,
reset,
}: {
error: Error &amp; { digest?: string };
reset: () =&gt; void;
}) {
return (
&lt;div&gt;
&lt;h2&gt;Something went wrong!&lt;/h2&gt;
&lt;p&gt;{error.message}&lt;/p&gt;
&lt;button onClick={reset}&gt;Try again&lt;/button&gt;
&lt;/div&gt;
);
}</code></pre>
<p><strong>Automatic Error boundary</strong> - catches errors in page and nested segments.</p>
<hr>
<h2>Server vs Client Components</h2>
<h3>Server Components (Default)</h3>
<pre><code class="lang-tsx">// app/page.tsx (Server Component by default)
import { prisma } from &#x27;@/lib/prisma&#x27;;
export default async function HomePage() {
// Fetch data directly in component
const users = await prisma.user.findMany();
return (
&lt;div&gt;
{users.map(user =&gt; (
&lt;div key={user.id}&gt;{user.name}&lt;/div&gt;
))}
&lt;/div&gt;
);
}</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>Zero JavaScript sent to client</li><li>Direct database access</li><li>Can use server-only code (Node.js APIs)</li><li>Better performance (no hydration cost)</li></ul>
<p><strong>Limitations</strong>:</p>
<ul><li>Cannot use hooks (useState, useEffect)</li><li>Cannot use browser APIs</li><li>Cannot use event handlers directly</li></ul>
<h3>Client Components</h3>
<pre><code class="lang-tsx">// app/components/Counter.tsx
&#x27;use client&#x27;; // Opt-in to Client Component
import { useState } from &#x27;react&#x27;;
export default function Counter() {
const [count, setCount] = useState(0);
return (
&lt;div&gt;
&lt;p&gt;Count: {count}&lt;/p&gt;
&lt;button onClick={() =&gt; setCount(count + 1)}&gt;Increment&lt;/button&gt;
&lt;/div&gt;
);
}</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Need hooks (useState, useEffect, useContext)</li><li>Need event handlers (onClick, onChange)</li><li>Need browser APIs (localStorage, window)</li><li>Need third-party libraries that use hooks</li></ul>
<p><strong>Add <code>&#x27;use client&#x27;</code></strong> at top of file.</p>
<h3>Mixing Server and Client Components</h3>
<pre><code class="lang-tsx">// app/page.tsx (Server Component)
import { prisma } from &#x27;@/lib/prisma&#x27;;
import Counter from &#x27;./components/Counter&#x27;; // Client Component
export default async function HomePage() {
const users = await prisma.user.findMany();
return (
&lt;div&gt;
&lt;h1&gt;Users: {users.length}&lt;/h1&gt;
{/* Server Component data passed to Client Component */}
&lt;Counter initialCount={users.length} /&gt;
&lt;/div&gt;
);
}</code></pre>
<p><strong>Rules</strong>:</p>
<ul><li>Server Components can import Client Components</li><li>Client Components cannot import Server Components directly</li><li>Pass Server Component data as props to Client Components</li></ul>
<h3>Composition Pattern (Server in Client)</h3>
<pre><code class="lang-tsx">// app/components/ClientWrapper.tsx
&#x27;use client&#x27;;
export default function ClientWrapper({ children }: { children: React.ReactNode }) {
const [isOpen, setIsOpen] = useState(false);
return (
&lt;div&gt;
&lt;button onClick={() =&gt; setIsOpen(!isOpen)}&gt;Toggle&lt;/button&gt;
{isOpen &amp;&amp; children}
&lt;/div&gt;
);
}
// app/page.tsx (Server Component)
import ClientWrapper from &#x27;./components/ClientWrapper&#x27;;
import ServerData from &#x27;./components/ServerData&#x27;; // Server Component
export default function Page() {
return (
&lt;ClientWrapper&gt;
{/* ServerData rendered on server, passed as children */}
&lt;ServerData /&gt;
&lt;/ClientWrapper&gt;
);
}</code></pre>
<p><strong>Pass Server Components as children</strong> to Client Components.</p>
<hr>
<h2>Layouts and Templates</h2>
<h3>Nested Layouts</h3>
<pre><code class="lang-tsx">// app/layout.tsx (Root Layout)
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
&lt;html&gt;
&lt;body&gt;
&lt;nav&gt;Global Nav&lt;/nav&gt;
{children}
&lt;/body&gt;
&lt;/html&gt;
);
}
// app/dashboard/layout.tsx (Dashboard Layout)
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
return (
&lt;div&gt;
&lt;aside&gt;Dashboard Sidebar&lt;/aside&gt;
&lt;main&gt;{children}&lt;/main&gt;
&lt;/div&gt;
);
}
// app/dashboard/page.tsx
export default function DashboardPage() {
return &lt;h1&gt;Dashboard&lt;/h1&gt;;
}</code></pre>
<p><strong>Result</strong>:</p>
<pre><code>&lt;html&gt;
&lt;body&gt;
&lt;nav&gt;Global Nav&lt;/nav&gt;
&lt;div&gt;
&lt;aside&gt;Dashboard Sidebar&lt;/aside&gt;
&lt;main&gt;
&lt;h1&gt;Dashboard&lt;/h1&gt;
&lt;/main&gt;
&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;</code></pre>
<p><strong>Layouts persist across navigation</strong> - no re-render when switching pages in same layout.</p>
<h3>Templates (Re-rendered on Navigation)</h3>
<pre><code class="lang-tsx">// app/dashboard/template.tsx
export default function DashboardTemplate({ children }: { children: React.ReactNode }) {
return (
&lt;div className=&quot;fade-in&quot;&gt;
{children}
&lt;/div&gt;
);
}</code></pre>
<p><strong>Difference from Layout</strong>:</p>
<ul><li>Layout: Persists, state preserved</li><li>Template: Re-rendered on navigation, state reset</li></ul>
<p><strong>Use templates for</strong>:</p>
<ul><li>Page transitions/animations</li><li>Resetting state on navigation</li><li>useEffect that should run on every page load</li></ul>
<hr>
<h2>Routing Patterns</h2>
<h3>Dynamic Routes</h3>
<pre><code>app/
blog/
[slug]/
page.tsx # /blog/:slug</code></pre>
<pre><code class="lang-tsx">// app/blog/[slug]/page.tsx
export default function BlogPost({ params }: { params: { slug: string } }) {
return &lt;h1&gt;Post: {params.slug}&lt;/h1&gt;;
}</code></pre>
<h3>Catch-All Routes</h3>
<pre><code>app/
docs/
[...slug]/
page.tsx # /docs/a, /docs/a/b, /docs/a/b/c</code></pre>
<pre><code class="lang-tsx">// app/docs/[...slug]/page.tsx
export default function DocsPage({ params }: { params: { slug: string[] } }) {
// /docs/a/b/c -&gt; params.slug = [&#x27;a&#x27;, &#x27;b&#x27;, &#x27;c&#x27;]
return &lt;h1&gt;Docs: {params.slug.join(&#x27; &gt; &#x27;)}&lt;/h1&gt;;
}</code></pre>
<h3>Optional Catch-All Routes</h3>
<pre><code>app/
shop/
[[...slug]]/
page.tsx # /shop, /shop/a, /shop/a/b</code></pre>
<h3>Route Groups (Organization)</h3>
<pre><code>app/
(marketing)/ # Group, not in URL
page.tsx # /
about/
page.tsx # /about
(shop)/
products/
page.tsx # /products
(dashboard)/
settings/
page.tsx # /settings</code></pre>
<p><strong>Parentheses</strong> exclude folder from URL path.</p>
<p><strong>Use for</strong>:</p>
<ul><li>Organizing routes</li><li>Different layouts for different sections</li><li>Splitting app into logical segments</li></ul>
<h3>Parallel Routes</h3>
<pre><code>app/
@analytics/ # Parallel slot
page.tsx
@team/ # Parallel slot
page.tsx
layout.tsx
page.tsx</code></pre>
<pre><code class="lang-tsx">// app/layout.tsx
export default function Layout({
children,
analytics,
team,
}: {
children: React.ReactNode;
analytics: React.ReactNode;
team: React.ReactNode;
}) {
return (
&lt;div&gt;
{children}
&lt;div className=&quot;grid grid-cols-2&quot;&gt;
{analytics}
{team}
&lt;/div&gt;
&lt;/div&gt;
);
}</code></pre>
<p><strong>Use for</strong>:</p>
<ul><li>Multiple sections loading independently</li><li>Conditional rendering of sections</li><li>Complex dashboard layouts</li></ul>
<hr>
<h2>Data Fetching</h2>
<h3>Async Server Components</h3>
<pre><code class="lang-tsx">// app/posts/page.tsx
async function getPosts() {
const res = await fetch(&#x27;https://api.example.com/posts&#x27;, {
next: { revalidate: 3600 } // Cache for 1 hour
});
if (!res.ok) throw new Error(&#x27;Failed to fetch&#x27;);
return res.json();
}
export default async function PostsPage() {
const posts = await getPosts();
return (
&lt;div&gt;
{posts.map((post: Post) =&gt; (
&lt;div key={post.id}&gt;{post.title}&lt;/div&gt;
))}
&lt;/div&gt;
);
}</code></pre>
<p><strong>Fetch options</strong>:</p>
<pre><code class="lang-tsx">// Static (cached forever, revalidate on build)
fetch(url, { cache: &#x27;force-cache&#x27; })
// Dynamic (no cache, fetch on every request)
fetch(url, { cache: &#x27;no-store&#x27; })
// Revalidate (cache, revalidate after N seconds)
fetch(url, { next: { revalidate: 60 } })</code></pre>
<h3>Streaming with Suspense</h3>
<pre><code class="lang-tsx">// app/dashboard/page.tsx
import { Suspense } from &#x27;react&#x27;;
async function Analytics() {
const data = await fetchAnalytics(); // Slow
return &lt;div&gt;Analytics: {data.value}&lt;/div&gt;;
}
async function RecentSales() {
const sales = await fetchSales(); // Fast
return &lt;div&gt;Sales: {sales.length}&lt;/div&gt;;
}
export default function Dashboard() {
return (
&lt;div&gt;
&lt;h1&gt;Dashboard&lt;/h1&gt;
{/* RecentSales loads first, Analytics streams in */}
&lt;Suspense fallback={&lt;div&gt;Loading analytics...&lt;/div&gt;}&gt;
&lt;Analytics /&gt;
&lt;/Suspense&gt;
&lt;Suspense fallback={&lt;div&gt;Loading sales...&lt;/div&gt;}&gt;
&lt;RecentSales /&gt;
&lt;/Suspense&gt;
&lt;/div&gt;
);
}</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>Faster initial page load</li><li>Progressive rendering</li><li>Independent loading states</li></ul>
<hr>
<h2>Server Actions</h2>
<h3>Form Actions</h3>
<pre><code class="lang-tsx">// app/actions.ts
&#x27;use server&#x27;;
import { revalidatePath } from &#x27;next/cache&#x27;;
export async function createPost(formData: FormData) {
const title = formData.get(&#x27;title&#x27;) as string;
const content = formData.get(&#x27;content&#x27;) as string;
// Database insert
await prisma.post.create({
data: { title, content }
});
// Revalidate cache
revalidatePath(&#x27;/posts&#x27;);
}
// app/posts/new/page.tsx
import { createPost } from &#x27;@/app/actions&#x27;;
export default function NewPostPage() {
return (
&lt;form action={createPost}&gt;
&lt;input name=&quot;title&quot; required /&gt;
&lt;textarea name=&quot;content&quot; required /&gt;
&lt;button type=&quot;submit&quot;&gt;Create Post&lt;/button&gt;
&lt;/form&gt;
);
}</code></pre>
<p><strong>Progressive enhancement</strong> - works without JavaScript.</p>
<h3>Client-Side Actions</h3>
<pre><code class="lang-tsx">// app/components/PostForm.tsx
&#x27;use client&#x27;;
import { useFormStatus } from &#x27;react-dom&#x27;;
import { createPost } from &#x27;@/app/actions&#x27;;
function SubmitButton() {
const { pending } = useFormStatus();
return (
&lt;button type=&quot;submit&quot; disabled={pending}&gt;
{pending ? &#x27;Creating...&#x27; : &#x27;Create Post&#x27;}
&lt;/button&gt;
);
}
export default function PostForm() {
return (
&lt;form action={createPost}&gt;
&lt;input name=&quot;title&quot; required /&gt;
&lt;textarea name=&quot;content&quot; required /&gt;
&lt;SubmitButton /&gt;
&lt;/form&gt;
);
}</code></pre>
<h3>Revalidation</h3>
<pre><code class="lang-tsx">&#x27;use server&#x27;;
import { revalidatePath, revalidateTag } from &#x27;next/cache&#x27;;
export async function updatePost(id: string, data: any) {
await prisma.post.update({ where: { id }, data });
// Revalidate specific path
revalidatePath(&#x27;/posts&#x27;);
revalidatePath(`/posts/${id}`);
// Or revalidate by tag
revalidateTag(&#x27;posts&#x27;);
}</code></pre>
<hr>
<h2>Metadata and SEO</h2>
<h3>Static Metadata</h3>
<pre><code class="lang-tsx">// app/page.tsx
import type { Metadata } from &#x27;next&#x27;;
export const metadata: Metadata = {
title: &#x27;Home Page&#x27;,
description: &#x27;Welcome to our site&#x27;,
openGraph: {
title: &#x27;Home Page&#x27;,
description: &#x27;Welcome to our site&#x27;,
images: [&#x27;/og-image.png&#x27;],
},
};
export default function HomePage() {
return &lt;h1&gt;Home&lt;/h1&gt;;
}</code></pre>
<h3>Dynamic Metadata</h3>
<pre><code class="lang-tsx">// app/posts/[slug]/page.tsx
import type { Metadata } from &#x27;next&#x27;;
export async function generateMetadata(
{ params }: { params: { slug: string } }
): Promise&lt;Metadata&gt; {
const post = await getPost(params.slug);
return {
title: post.title,
description: post.excerpt,
openGraph: {
title: post.title,
description: post.excerpt,
images: [post.image],
},
};
}
export default function PostPage({ params }: { params: { slug: string } }) {
return &lt;div&gt;Post&lt;/div&gt;;
}</code></pre>
<hr>
<h2>Optimization Patterns</h2>
<h3>Route Handlers (API Routes)</h3>
<pre><code class="lang-tsx">// app/api/users/route.ts
import { NextRequest, NextResponse } from &#x27;next/server&#x27;;
export async function GET(request: NextRequest) {
const users = await prisma.user.findMany();
return NextResponse.json(users);
}
export async function POST(request: NextRequest) {
const data = await request.json();
const user = await prisma.user.create({ data });
return NextResponse.json(user, { status: 201 });
}</code></pre>
<h3>Middleware</h3>
<pre><code class="lang-tsx">// middleware.ts
import { NextRequest, NextResponse } from &#x27;next/server&#x27;;
export function middleware(request: NextRequest) {
const token = request.cookies.get(&#x27;token&#x27;);
if (!token &amp;&amp; request.nextUrl.pathname.startsWith(&#x27;/dashboard&#x27;)) {
return NextResponse.redirect(new URL(&#x27;/login&#x27;, request.url));
}
return NextResponse.next();
}
export const config = {
matcher: &#x27;/dashboard/:path*&#x27;,
};</code></pre>
<hr>
<h2>Quick Reference</h2>
<h3>File Conventions</h3>
<pre><code>page.tsx # Route UI
layout.tsx # Persistent layout
template.tsx # Re-rendered layout
loading.tsx # Loading UI (Suspense)
error.tsx # Error UI (Error boundary)
not-found.tsx # 404 UI
route.ts # API endpoint</code></pre>
<h3>Server vs Client Decision Tree</h3>
<pre><code>Need interactivity (state, events)? → Client Component
Need browser APIs? → Client Component
Need server-only code? → Server Component
Need data fetching? → Server Component (default)
Unsure? → Start with Server Component, convert if needed</code></pre>
<h3>Fetch Caching</h3>
<pre><code class="lang-tsx">// Static (build time)
fetch(url, { cache: &#x27;force-cache&#x27; })
// Dynamic (every request)
fetch(url, { cache: &#x27;no-store&#x27; })
// Revalidate (time-based)
fetch(url, { next: { revalidate: 60 } })
// Revalidate (tag-based)
fetch(url, { next: { tags: [&#x27;posts&#x27;] } })</code></pre>
<hr>
<h2>Related Skills</h2>
<ul><li><code>react-component-patterns.md</code> - Component composition, custom hooks</li><li><code>react-state-management.md</code> - Client-side state management</li><li><code>react-data-fetching.md</code> - SWR, React Query for Client Components</li><li><code>nextjs-seo.md</code> - Metadata API, structured data, sitemaps</li><li><code>frontend-performance.md</code> - Bundle optimization, image optimization</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-18 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/frontend-nextjs-app-router.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>