Skill: goldath/nextjs-patterns (version 1.0.0)

--- name: nextjs-patterns description: > Apply Next.js 15 best practices and modern patterns including App Router, Server Components, Server Actions, caching strategies, and performance optimization. Use when building or reviewing Next.js 15 applications to ensure idiomatic, production-ready code. --- # Next.js 15 Best Practices ## Core Principles 1. **Default to Server Components** — only add `"use client"` when you need interactivity or browser APIs 2. **Colocate by feature** — keep components, hooks, and utils near the routes that use them 3. **Type everything** — leverage TypeScript with strict mode enabled 4. **Cache deliberately** — understand the four caching layers and opt in/out explicitly ## Project Structure ``` app/ (marketing)/ # route group: no URL segment page.tsx (dashboard)/ layout.tsx [id]/ page.tsx api/ route.ts components/ ui/ # shared, "dumb" UI components features/ # feature-specific components lib/ db.ts # database client (singleton) auth.ts # auth helpers utils.ts ``` ## Server vs. Client Components ```tsx // ✅ Server Component (default) — runs on server, no JS sent to client export default async function ProductList() { const products = await db.product.findMany() return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul> } // ✅ Client Component — only when needed "use client" import { useState } from "react" export function Counter() { const [n, setN] = useState(0) return <button onClick={() => setN(n + 1)}>{n}</button> } ``` ## Data Fetching Patterns ```tsx // Parallel fetching (avoid sequential waterfalls) export default async function Dashboard() { const [user, stats] = await Promise.all([ fetchUser(), fetchStats(), ]) return <View user={user} stats={stats} /> } // fetch with cache control const data = await fetch("https://api.example.com/data", { next: { revalidate: 60 }, // ISR: revalidate every 60s // cache: "no-store" // always fresh // cache: "force-cache" // static, until manual revalidation }) ``` ## Server Actions ```tsx // app/actions.ts "use server" import { revalidatePath } from "next/cache" export async function createPost(formData: FormData) { const title = formData.get("title") as string await db.post.create({ data: { title } }) revalidatePath("/posts") } // app/posts/new/page.tsx import { createPost } from "../actions" export default function NewPost() { return ( <form action={createPost}> <input name="title" /> <button type="submit">Create</button> </form> ) } ``` ## Metadata & SEO ```tsx // Static metadata export const metadata = { title: "My App", description: "...", } // Dynamic metadata export async function generateMetadata({ params }) { const post = await fetchPost(params.slug) return { title: post.title, description: post.excerpt } } ``` ## Error & Loading States ```tsx // app/posts/loading.tsx — automatic Suspense boundary export default function Loading() { return <Skeleton /> } // app/posts/error.tsx — automatic error boundary "use client" export default function Error({ error, reset }) { return <button onClick={reset}>Retry: {error.message}</button> } ``` ## Performance Checklist - [ ] Images use `next/image` with explicit `width`/`height` - [ ] Fonts use `next/font` (zero layout shift) - [ ] Dynamic imports for heavy client components: `dynamic(() => import(...))` - [ ] `generateStaticParams` for known dynamic routes - [ ] Bundle analyzer run: `ANALYZE=true next build` - [ ] Partial Prerendering (PPR) considered for mixed static/dynamic pages ## References See `references/` folder for routing patterns, caching deep-dive, and migration guide.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)