nextjs · diff
git:20260504.759031f to git:20260803.af106c2
15 added, 73 removed. Audit A to A.
---
name: nextjs
- description: "Apply these opinionated Next.js 14+ recipes when building App Router apps: Server Components, Server Actions, data fetching/caching/revalidation, image/font/bundle optimization, Metadata API for SEO, Vercel deployment."
+ description: "Apply these opinionated Next.js conventions whenever writing or reviewing App Router code (14+): Server Components by default, where the 'use client' boundary belongs, the caching defaults that changed in Next 15, tag-based revalidation, treating Server Actions as public endpoints, the Metadata API, and next/image and next/font."
---
- # Next.js Developer
-
- Senior Next.js developer with expertise in Next.js 14+ App Router, server components, and full-stack deployment with focus on performance and SEO excellence.
-
- ## Role Definition
-
- You are a senior full-stack developer with 10+ years of React/Next.js experience. You specialize in Next.js 14+ App Router (NOT Pages Router), React Server Components, server actions, and production-grade deployment. You build blazing-fast, SEO-optimized applications achieving Core Web Vitals scores > 90.
-
- ## When to Use This Skill
-
- - Building Next.js 14+ applications with App Router
- - Implementing server components and server actions
- - Setting up data fetching, caching, and revalidation
- - Optimizing performance (images, fonts, bundles)
- - Implementing SEO with Metadata API
- - Deploying to Vercel or self-hosting
-
- ## Core Workflow
-
- 1. **Architecture planning** - Define app structure, routes, layouts, rendering strategy
- 2. **Implement routing** - Create App Router structure with layouts, templates, loading states
- 3. **Data layer** - Setup server components, data fetching, caching, revalidation
- 4. **Optimize** - Images, fonts, bundles, streaming, edge runtime
- 5. **Deploy** - Production build, environment setup, monitoring
-
- ## Reference Guide
-
- Load detailed guidance based on context:
-
- | Topic | Reference | Load When |
- | --- | --- | --- |
- | App Router | `references/app-router.md` | File-based routing, layouts, templates, route groups |
- | Server Components | `references/server-components.md` | RSC patterns, streaming, client boundaries |
- | Server Actions | `references/server-actions.md` | Form handling, mutations, revalidation |
- | Data Fetching | `references/data-fetching.md` | fetch, caching, ISR, on-demand revalidation |
- | Deployment | `references/deployment.md` | Vercel, self-hosting, Docker, optimization |
-
- ## Constraints
-
- ### MUST DO
-
- - Use App Router (NOT Pages Router)
- - Use TypeScript with strict mode
- - Use Server Components by default
- - Mark Client Components with 'use client'
- - Use native fetch with caching options
- - Use Metadata API for SEO
- - Optimize images with next/image
- - Use proper loading and error boundaries
- - Target Core Web Vitals > 90
-
- ### MUST NOT DO
-
- - Use Pages Router (pages/ directory)
- - Make all components client components
- - Fetch data in client components unnecessarily
- - Skip image optimization
- - Hardcode metadata in components
- - Use external state managers without need
- - Skip error boundaries
- - Deploy without build optimization
-
- ## Output Templates
-
- When implementing Next.js features, provide:
+ # Next.js
- 1. App structure (route organization)
- 2. Layout/page components with proper data fetching
- 3. Server actions if mutations needed
- 4. Configuration (next.config.js, TypeScript)
- 5. Brief explanation of rendering strategy
+ House conventions for Next.js App Router (14+). Apply them to code you are writing or changing — don't migrate untouched routes unless asked.
- ## Knowledge Reference
+ ## Conventions
- Next.js 14+, App Router, React Server Components, Server Actions, Streaming SSR, Partial Prerendering, next/image, next/font, Metadata API, Route Handlers, Middleware, Edge Runtime, Turbopack, Vercel deployment
+ - **App Router only.** Never add to `pages/`. If a project still has one, new work goes in `app/` and the two coexist until someone schedules the migration.
+ - **Server Components by default.** `'use client'` marks a leaf that needs interactivity, not a page. Everything above that marker ships to the browser too, so the boundary belongs as deep in the tree as it will go.
+ - **Verify caching behaviour against the installed version — it changed.** Through Next 14, `fetch` was cached by default and you opted out; from Next 15, `fetch`, Route Handlers, and client navigation are uncached by default and you opt in. Assuming the wrong default gives you either stale pages or an origin taking every request. Check `package.json`, then set the intent explicitly (`cache`, `next.revalidate`, or route segment config) rather than relying on whatever the default happens to be.
+ - **`params` and `searchParams` are Promises from Next 15 on** — `const { slug } = await params`. Code written against 14 destructures them synchronously and breaks on upgrade, so check the installed major before copying either form.
+ - **A `layout.tsx` auth check is not a security boundary.** Layouts don't re-render on every navigation between their child routes, so the check can be skipped on client-side transitions. Enforce access in middleware and again where the data is read; the layout check is UX, not enforcement.
+ - **Tag what you fetch, revalidate by tag.** `next: { tags: ['user'] }` plus `revalidateTag('user')` after a mutation invalidates exactly the affected data. Time-based revalidation is a guess about staleness; tags are a fact about it.
+ - **Server Actions are public endpoints.** They are reachable by anyone who can find the action ID, so every one re-checks auth and re-validates its input server-side. The form it was rendered behind proves nothing about the caller.
+ - **Fetch in the component that renders the data.** React dedupes identical requests within a render pass, so prop-drilling data down to avoid a "duplicate" fetch buys nothing and couples the tree.
+ - **Metadata through the Metadata API** — `export const metadata` or `generateMetadata`. Hand-written `<head>` tags in a component don't merge across nested layouts and silently lose out to the framework's.
+ - **`next/image` and `next/font` always.** They exist for the two largest Core Web Vitals costs: unsized images causing layout shift, and font loading blocking first paint. A raw `<img>` gives up both.
+ - **`loading.tsx` and `error.tsx` per meaningful route segment.** The route boundary is where a failure should be contained; without `error.tsx`, one segment's error takes down the layout around it.