---
name: Next.js Development
description: Guidelines and best practices for Next.js App Router development
---

# Next.js Development Skill

> **Note**: For comprehensive Next.js performance optimization and best practices, refer to the [React Best Practices](../react/SKILL.md) skill which includes 40+ rules covering both React and Next.js.

This skill provides Next.js-specific guidance that complements the React best practices.

## Core Principles

- **App Router First**: Prefer the `app/` directory over `pages/` for new projects.
- **Server Components by Default**: Leverage React Server Components (RSC) to reduce client-side JavaScript.
- **Data Fetching**: Use `fetch` directly in Server Components with appropriate revalidation strategies.

## Quick Reference

### Server vs. Client Components
- Keep components as **Server Components** as much as possible.
- Use `'use client'` directive only when necessary (interactivity, browser APIs, state/hooks).
- Move client-side logic to the "leaves" of your component tree.

### Routing and Layouts
- Utilize `layout.tsx` for shared UI across routes (preserves state on navigation).
- Use `loading.tsx` for instant loading states with React Suspense.
- Implement `error.tsx` for granular error handling.

### Data Fetching and Caching
- Use `generateStaticParams` for static site generation (SSG).
- Leverage Next.js extended `fetch` for caching and revalidation:
  ```typescript
  fetch('https://api.example.com/data', { 
    next: { revalidate: 3600 } 
  })
  ```
- Use Server Actions (`'use server'`) for mutations.

### Optimization
- Use `next/image` for automatic image optimization.
- Use `next/font` for optimized custom fonts.
- Use `next/script` for third-party script management.

## Project Structure (App Router)

```
app/              # Routes, layouts, and components
├── layout.tsx    # Root layout
├── page.tsx      # Home page
├── about/
│   └── page.tsx
components/       # Shared UI components
├── ui/           # Basic UI elements
├── features/     # Feature-specific components
lib/              # Utility functions and shared logic
types/            # TypeScript definitions
```

## Code Snippets

### Server Component Data Fetching
```tsx
async function getData() {
  const res = await fetch('https://api.example.com/data', { 
    next: { revalidate: 60 } 
  });
  if (!res.ok) throw new Error('Failed to fetch data');
  return res.json();
}

export default async function Page() {
  const data = await getData();
  return <main>{/* Render data */}</main>;
}
```

### Server Action
```tsx
// actions.ts
'use server'

import { revalidatePath } from 'next/cache';

export async function createItem(formData: FormData) {
  // Logic to save data
  revalidatePath('/items');
}
```

### Dynamic Import
```tsx
import dynamic from 'next/dynamic';

const HeavyComponent = dynamic(
  () => import('./HeavyComponent'),
  { ssr: false, loading: () => <p>Loading...</p> }
);
```

## Additional Resources

For detailed performance optimization rules including:
- Eliminating waterfalls
- Bundle size optimization
- Server-side performance
- Re-render optimization

Please refer to the [React Best Practices](../react/SKILL.md) skill which provides comprehensive coverage of Next.js optimization patterns.