skills-nextjs

Complete Next.js 16 (App Router) best practices skill system for Claude Code. Install once, get expert-level Next.js guidance on every topic — App Router, Server Components, Server Actions, Auth, Security, Forms, ISR, Caching, Deployment, and more.

Installation

# Using npm
npm install skills-nextjs

# Or manually add to ~/.claude/settings.json:
{
  "skills": [
    {
      "name": "nextjs",
      "path": "path/to/node_modules/skills-nextjs"
    }
  ]
}

Skills Overview

| Skill | Slash Command | What It Covers | |-------|--------------|----------------| | Master Index | (auto-loaded) | Decision tree — picks the right skill for your task | | core | /nextjs-core | App Router, layouts, pages, error/loading boundaries | | routing | /nextjs-routing | Dynamic routes, route groups, parallel & intercepted routes | | data-fetching | /nextjs-data-fetching | Server Components, fetch, ORMs, React.cache | | streaming | /nextjs-streaming | Suspense, loading.js, use() API, skeleton UI | | mutations | /nextjs-mutations | Server Actions, revalidatePath/Tag, redirect | | forms | /nextjs-forms | Server Action forms, Zod validation, useActionState | | caching | /nextjs-caching | use cache, cacheLife, cacheTag, Partial Prerendering | | route-handlers | /nextjs-route-handlers | route.ts, NextRequest/NextResponse, webhooks | | proxy | /nextjs-proxy | proxy.ts, CSP nonce, security headers, auth guards | | auth | /nextjs-auth | Sessions, DAL, DTOs, JOSE, Proxy guard | | security | /nextjs-security | CSP, taint APIs, server-only, XSS/CSRF, IDOR | | styling | /nextjs-styling | Tailwind v4, CSS Modules, styled-components | | images-fonts | /nextjs-images-fonts | next/image, next/font, blur placeholders | | metadata | /nextjs-metadata | Metadata API, OG images, sitemap, JSON-LD | | isr | /nextjs-isr | Incremental Static Regeneration, revalidate | | i18n | /nextjs-i18n | Accept-Language, dictionaries, locale routing | | mdx | /nextjs-mdx | @next/mdx, mdx-components.tsx, MDX pages | | deployment | /nextjs-deployment | Docker, Vercel, adapters, CI caching | | performance | /nextjs-performance | next/dynamic, Turbopack, bundle optimization | | testing | /nextjs-testing | Playwright, Vitest, Jest, Cypress | | advanced | /nextjs-advanced | Custom server, instrumentation, Draft Mode, PWA |

Quick Decision Tree

What are you building?
│
├─ A new page or layout
│  └─ /nextjs-core  → layout.tsx, page.tsx, template, error, loading
│
├─ Dynamic URLs (e.g. /blog/[slug])
│  └─ /nextjs-routing  → [slug], [...catch-all], route groups, parallel routes
│
├─ Fetching data
│  ├─ Server Component (recommended)
│  │  └─ /nextjs-data-fetching  → fetch, ORMs, React.cache
│  ├─ Slow data / streaming UI
│  │  └─ /nextjs-streaming  → Suspense, loading.js, use() API
│  └─ Cached / static content
│     └─ /nextjs-caching  → use cache, cacheLife, revalidateTag
│
├─ Form submission or data mutation
│  ├─ Simple Server Action
│  │  └─ /nextjs-mutations  → 'use server', revalidatePath
│  └─ Full form with validation
│     └─ /nextjs-forms  → Zod, useActionState, useOptimistic
│
├─ API endpoint
│  └─ /nextjs-route-handlers  → route.ts, HTTP verbs, cookies
│
├─ Auth (login, sessions, permissions)
│  └─ /nextjs-auth  → JOSE sessions, DAL, DTOs, Proxy guard
│
├─ Security (CSP, XSS, secrets)
│  └─ /nextjs-security  → CSP nonce, taint APIs, server-only
│
├─ CSS / Styling
│  └─ /nextjs-styling  → Tailwind v4, CSS Modules, CSS-in-JS
│
├─ SEO / Metadata
│  └─ /nextjs-metadata  → generateMetadata, OG images, sitemap
│
├─ Static + dynamic pages (ISR)
│  └─ /nextjs-isr  → revalidate, generateStaticParams
│
├─ Multi-language site
│  └─ /nextjs-i18n  → Accept-Language, dictionaries
│
├─ Markdown content
│  └─ /nextjs-mdx  → @next/mdx, mdx-components.tsx
│
├─ Production deployment
│  ├─ Docker / Node.js
│  │  └─ /nextjs-deployment  → Docker, Vercel, adapters, CI caching
│  └─ Performance optimization
│     └─ /nextjs-performance  → next/dynamic, Turbopack
│
└─ Testing
   └─ /nextjs-testing  → Playwright, Vitest, Jest, Cypress

Skill Format

Each skill is a markdown file containing:

• Overview — what it is and when to use it
• Prerequisites — which skills are required first
• Step-by-step guide — copy-paste code with annotations
• Patterns — composable patterns with other skills
• Gotchas — common pitfalls and fixes
• Code examples — production-ready, fully annotated snippets
• File templates — exact stubs to generate

Version

Based on Next.js 16 (March 2026) with full App Router coverage, Cache Components, Server Actions, Proxy (middleware), and Partial Prerendering.

Contributing

See SPEC.md for the full system design. Skills are organized in skills/. Add a new skill by creating skills/<name>.md and updating this README.