| name | nextjs-patterns |
| type | reference |
| description | Comprehensive Next.js development patterns for App Router, Server Components, TypeScript, and Tailwind CSS. Covers foundational principles, data fetching, routing, performance, and an 8-phase development workflow. Also includes Server Actions and Metadata patterns. |
| paths | ["**/*.tsx","**/*.jsx","**/next.config.*","**/app/**/*.ts","**/tailwind.config.*"] |
| when_to_use | Building or optimizing Next.js 14+ / 15+ applications with App Router, Server Components, streaming, or Server Actions. |
| allowed-tools | Read, Glob, Grep, Write, Edit, Bash |
| user-invocable | true |
| effort | 3 |
Next.js Development Patterns
Comprehensive patterns and best practices for Next.js 14+ / 15+ App Router architecture, Server Components, and modern full-stack React development.
1. Foundational Principles
Server vs Client Components
- Server (Default): Use for data fetching, layouts, and static content.
- Client ('use client'): Use for interactivity (useState, useEffect), event handlers, and browser-only APIs.
- Decision Rule: Stay on the server as long as possible. Split components so the interactive "leaf nodes" are client-side while the data-heavy "branch nodes" remain on the server.
Routing & Organization
- App Router: Use the
app/ directory for file-based routing.
- Route Groups:
(group-name) for organization without affecting URL structure.
- Special Files:
page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx.
- Advanced Routing: Parallel routes (
@slot) and Intercepting routes ((.)).
2. Data Fetching & Caching
Strategy Matrix
| Pattern | Use Case | Implementation |
|---|
| Static | Blog posts, marketing | Cached at build time |
| ISR | Products, news | revalidate: 60 |
| Dynamic | User dashboards, search | no-store or force-dynamic |
Patterns
- Server Fetching: Fetch data directly in Server Components using
async/await.
- Streaming: Use
Suspense and loading.tsx to stream UI to the client.
- Server Actions: Perform mutations with
use server functions. Validate with Zod.
3. 8-Phase Development Workflow
Phase 1: Project Setup
Scaffold with @app-builder, configure TypeScript, and set up ESLint/Prettier.
Phase 2: Component Architecture
Design hierarchy and implement base layout components using @frontend-developer and @react-patterns.
Phase 3: Styling & Design
Configure Tailwind CSS v4 and design tokens using @tailwind-patterns and @frontend-design.
Phase 4: Data Fetching
Implement Server Component data fetching and set up React Query/SWR if client-side fetching is needed.
Phase 5: Routing & Navigation
Set up file-based routing, dynamic routes, and handle redirects/guards.
Phase 6: Forms & Validation
Use React Hook Form and Zod for robust, type-safe data entry.
Phase 7: Testing
Write unit/integration tests with Vitest and E2E flows with @playwright-skill.
Phase 8: Optimization & Deploy
Analyze bundle size, optimize images with next/image, and deploy to Vercel/similar.
4. Performance & Metadata
- Images: Always use
next/image. Set priority for LCP elements.
- Dynamic Imports: Use for heavy client-side libraries.
- Metadata API: Use
generateMetadata for dynamic SEO tags per route.
Resources & Anti-Patterns
- implementation-playbook.md: Detailed code examples for every pattern.
- Anti-Pattern: Using
'use client' at the top level of every file.
- Anti-Pattern: Fetching data inside
useEffect for information available on first load.
Guidance: If you need deeper walkthroughs, refer to the resources/ folder within this skill.
