nextjs-optimization

What this skill does

# Next.js 15 Optimization Skill

## Objective

Optimize Next.js applications to achieve:
- Perfect Core Web Vitals scores (LCP < 2.5s, FID < 100ms, CLS < 0.1)
- Fast page load times and optimal rendering strategies
- Efficient data fetching and caching
- Production-ready build configuration
- SEO and accessibility excellence

## When to Use This Skill

Auto-invoke when:
- Project uses Next.js (detected by `next` in dependencies)
- User mentions "optimize", "performance", "slow", or "Core Web Vitals"
- Before production deployment
- After adding new features or pages
- User requests Next.js-specific improvements

## Prerequisites Check

**Tools**: Read, Grep

1. **Verify Next.js version**:
   ```bash
   # Read package.json
   # Check for "next": "^15.0.0" or higher
   ```

2. **Detect App Router** (Next.js 13+):
   - Check for `app/` directory
   - Check for `layout.tsx`, `page.tsx` files

3. **Detect Pages Router** (Legacy):
   - Check for `pages/` directory
   - Suggest migration to App Router

## Optimization Categories

### 1. Rendering Strategy Optimization

**Goal**: Choose optimal rendering for each page/component

**Tools**: Read, Grep, Edit

#### 1.1 Server Components (Default in App Router)

**When to use**: 
- Data fetching from APIs/databases
- Heavy computation
- Access to backend resources

**Pattern**:
```typescript
// app/dashboard/page.tsx
export default async function DashboardPage() {
  const data = await fetchData(); // Runs on server
  return <Dashboard data={data} />;
}
```

**Check for violations**:
```bash
# Search for "use client" in components that don't need it
grep -r "use client" app/ | grep -v "onClick\|useState\|useEffect"
```

#### 1.2 Client Components

**When to use**:
- Interactive UI (onClick, forms)
- Browser APIs (window, localStorage)
- React hooks (useState, useEffect)

**Pattern**:
```typescript
// app/components/Counter.tsx
'use client';

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
```

**Optimization**: Keep client components small and leaf nodes

#### 1.3 Static Generation (SSG)

**When to use**: 
- Content that rarely changes
- Marketing pages, blogs, documentation

**Pattern**:
```typescript
export const revalidate = 3600; // Revalidate every hour

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);
  return <Article post={post} />;
}
```

#### 1.4 Dynamic Rendering with ISR

**When to use**:
- Content that changes periodically
- E-commerce products, user profiles

**Pattern**:
```typescript
export const revalidate = 60; // Revalidate every minute

export async function generateStaticParams() {
  const products = await getProducts();
  return products.map((p) => ({ slug: p.slug }));
}
```

### 2. Image Optimization

**Goal**: Optimize images for performance and Core Web Vitals

**Tools**: Grep, Read, Edit

#### 2.1 Use Next.js Image Component

**Find unoptimized images**:
```bash
grep -rn "<img " app/ src/
```

**Replace with**:
```typescript
import Image from 'next/image';

<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1200}
  height={600}
  priority // For above-the-fold images
  placeholder="blur" // Optional blur-up effect
/>
```

#### 2.2 Configure Image Domains

**Read next.config.js**:
```javascript
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
      },
    ],
    formats: ['image/avif', 'image/webp'], // Modern formats
  },
};
```

#### 2.3 Lazy Loading Strategy

- **priority**: Above-the-fold images (LCP candidates)
- **loading="lazy"**: Below-the-fold images (default)

### 3. Font Optimization

**Goal**: Eliminate FOUT/FOIT and improve font loading

**Tools**: Read, Edit

#### 3.1 Use next/font

**Pattern**:
```typescript
// app/layout.tsx
import { Inter } from 'next/font/google';

const inter = Inter({
  subsets: ['latin'],
  display: 'swap', // Prevent FOIT
  variable: '--font-inter',
});

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={inter.variable}>
      <body>{children}</body>
    </html>
  );
}
```

#### 3.2 Self-Hosted Fonts

```typescript
import localFont from 'next/font/local';

const customFont = localFont({
  src: './fonts/CustomFont.woff2',
  display: 'swap',
  variable: '--font-custom',
});
```

### 4. Data Fetching Optimization

**Goal**: Minimize waterfalls and optimize cache

**Tools**: Read, Grep, Edit

#### 4.1 Parallel Data Fetching

**Anti-pattern** (Sequential):
```typescript
const user = await getUser();
const posts = await getPosts(user.id); // Waits for user
```

**Optimized** (Parallel):
```typescript
const [user, posts] = await Promise.all([
  getUser(),
  getPosts(),
]);
```

#### 4.2 Streaming with Suspense

**Pattern**:
```typescript
import { Suspense } from 'react';

export default function Page() {
  return (
    <>
      <Header />
      <Suspense fallback={<Skeleton />}>
        <SlowComponent />
      </Suspense>
      <Footer />
    </>
  );
}
```

#### 4.3 Cache Configuration

```typescript
// Aggressive caching
fetch('https://api.example.com/data', {
  next: { revalidate: 3600 }, // Cache for 1 hour
});

// No caching
fetch('https://api.example.com/data', {
  cache: 'no-store', // Always fresh
});

// Opt out of caching
export const dynamic = 'force-dynamic';
```

### 5. Bundle Optimization

**Goal**: Reduce JavaScript bundle size

**Tools**: Bash, Read, Edit

#### 5.1 Analyze Bundle

```bash
# Add to package.json scripts
npm run build
npx @next/bundle-analyzer
```

#### 5.2 Dynamic Imports

**Find large components**:
```bash
find app -name "*.tsx" -exec wc -l {} \; | sort -rn | head -10
```

**Split with dynamic imports**:
```typescript
import dynamic from 'next/dynamic';

const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <Skeleton />,
  ssr: false, // Skip SSR if not needed
});
```

#### 5.3 Tree Shaking

**Check for barrel exports**:
```bash
grep -rn "export \* from" app/
```

**Replace with specific imports**:
```typescript
// Anti-pattern
import { Button, Card, Modal } from '@/components';

// Optimized
import { Button } from '@/components/Button';
```

### 6. Metadata & SEO

**Goal**: Perfect SEO and social sharing

**Tools**: Read, Edit

#### 6.1 Static Metadata

```typescript
// app/layout.tsx
export const metadata = {
  title: {
    default: 'My App',
    template: '%s | My App',
  },
  description: 'Description for SEO',
  openGraph: {
    title: 'My App',
    description: 'Description for social sharing',
    images: ['/og-image.jpg'],
  },
  twitter: {
    card: 'summary_large_image',
  },
};
```

#### 6.2 Dynamic Metadata

```typescript
export async function generateMetadata({ params }) {
  const post = await getPost(params.slug);
  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      images: [post.ogImage],
    },
  };
}
```

### 7. Production Configuration

**Goal**: Optimize next.config.js for production

**Tools**: Read, Edit

#### 7.1 Essential Config

```javascript
// next.config.js
module.exports = {
  reactStrictMode: true,
  poweredByHeader: false, // Security
  compress: true, // Gzip compression
  
  // Compiler optimizations
  compiler: {
    removeConsole: process.env.NODE_ENV === 'production',
  },
  
  // Image optimization
  images: {
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
  },
  
  // React Compiler (Next.js 15)
  experimental: {
    reactCompiler: true,
  },
};
```

#### 7.2 Turbopack (Development)

```json
// package.json
{
  "scripts": {
    "dev": "next dev --turbo"
  }
}
```

### 8. Core Web Vitals Optimization

**Goal**: Achieve perfect Lighthouse scores

**Tools**: Bash, Grep, Edit

#### 8.1 LCP (Largest Contentful Paint) < 2.5s

**Optimize**:
- Use `priority` on hero images
- Preload critical resources
- Server-side render a