Next.js 15 + App Router Specialist

Complete Next.js 15 reference for Quetrex development.

This skill provides comprehensive guidance on all Next.js 15 App Router patterns, ensuring agents implement modern Next.js correctly the first time.

CRITICAL RULES (NEVER VIOLATE)

These rules are NON-NEGOTIABLE. Violations will break builds.

1. ALWAYS use <Image> from next/image - NEVER use <img>

// ✅ ALWAYS DO THIS
import Image from 'next/image'

<Image src="/logo.png" alt="Logo" width={200} height={100} />
<Image src={user.avatar} alt={user.name} width={40} height={40} />

// ❌ NEVER DO THIS - BUILD WILL FAIL
<img src="/logo.png" alt="Logo" />
<img src={user.avatar} alt={user.name} />

Why: Next.js Image component provides automatic optimization, lazy loading, and prevents layout shift. ESLint is configured to fail builds on <img> usage.

2. Server Components are DEFAULT - only add 'use client' when needed

3. Never make async Client Components

4. Always specify cache strategy for fetch()

When to Use This Skill

Use this skill when working with:

• Creating new routes or pages
• Implementing data fetching (Server Components vs Client Components)
• Server vs Client Component decisions
• Server Actions and form handling
• Streaming and Suspense
• Metadata and SEO
• Route handlers (API routes)
• Caching strategies
• Performance optimization

Complete Documentation

This skill includes comprehensive guides covering every Next.js 15 pattern:

📁 App Router Complete Guide

45+ examples covering:

• File-based routing (page.tsx, layout.tsx, route.ts)
• Dynamic routes ([id], [...slug], [[...slug]])
• Route groups ((group))
• Private folders (_folder)
• Route handlers (API routes)
• Layouts and templates
• Loading UI (loading.tsx)
• Error boundaries (error.tsx, global-error.tsx)
• Not found pages (not-found.tsx)
• Parallel routes (@folder)
• Intercepting routes ((.)folder)
• Route segment config (dynamic, revalidate, runtime)

🔄 Data Fetching Complete Guide

35+ examples covering:

• Server Component data fetching (async/await)
• Client Component data fetching (useEffect, React Query, SWR)
• Parallel data fetching (Promise.all)
• Sequential data fetching (waterfall prevention)
• Streaming data (Suspense boundaries)
• Server-Sent Events (SSE for Quetrex voice)
• Data mutations (Server Actions)
• Optimistic updates (useOptimistic)
• Form handling (useFormStatus, useActionState)
• Request deduplication
• Preloading data

💾 Caching Strategies Guide

35+ examples covering:

• Request memoization (automatic deduplication)
• Data Cache (fetch cache behavior)
• Full Route Cache (static vs dynamic)
• Router Cache (client-side cache)
• Cache configuration (force-cache, no-store, revalidate)
• Cache tags (revalidateTag, revalidatePath)
• On-demand revalidation
• Time-based revalidation (ISR)
• Cache debugging techniques
• Opting out of caching

⚡ Server Actions Complete Guide

31+ examples covering:

• Basic Server Action patterns
• Form actions (progressive enhancement)
• Button actions (programmatic calls)
• useFormStatus hook (loading states)
• useActionState hook (state management)
• useOptimistic hook (optimistic UI)
• Error handling in actions
• Validation with Zod
• Returning JSON vs redirect
• Security (authentication, CSRF)
• Rate limiting
• Database transactions

🎯 Metadata API Guide

26+ examples covering:

• Static metadata (exported object)
• Dynamic metadata (generateMetadata)
• File-based metadata (icon.png, opengraph-image.png)
• Open Graph metadata
• Twitter Cards
• JSON-LD structured data
• Viewport configuration
• PWA manifest
• Robots.txt
• Sitemap generation

✅ Pattern Validator

Executable Python script that checks:

• Server Components don't use client-only APIs
• Client Components have 'use client' directive
• Data fetching uses proper cache strategy
• Server Actions are marked with 'use server'
• Metadata API used correctly
• Image optimization (<Image> not <img>)
• Dynamic imports for heavy components

Run with: python validate-patterns.py /path/to/src

Quick Reference

Server vs Client Components Decision Tree

Do you need interactivity (onClick, onChange, etc.)?
├─ YES → Client Component ('use client')
└─ NO → Server Component (default)

Do you need React hooks (useState, useEffect)?
├─ YES → Client Component
└─ NO → Server Component

Do you need browser APIs (window, localStorage)?
├─ YES → Client Component
└─ NO → Server Component

Do you need to fetch data?
├─ Use Server Component (preferred)
└─ Only use Client Component if data must be client-side

Is the component purely presentational?
└─ Server Component (better performance)

Common Patterns

1. Server Component Data Fetching

// app/projects/page.tsx
export default async function ProjectsPage() {
  const projects = await db.project.findMany()
  return <ProjectList projects={projects} />
}

2. Client Component with Interactivity

// components/ProjectCard.tsx
'use client'

import { useState } from 'react'

export function ProjectCard({ project }: Props) {
  const [loading, setLoading] = useState(false)

  const handleDelete = async () => {
    setLoading(true)
    await deleteProject(project.id)
    setLoading(false)
  }

  return (
    <div>
      <h2>{project.name}</h2>
      <button onClick={handleDelete} disabled={loading}>
        Delete
      </button>
    </div>
  )
}

3. Server Action with Form

// app/actions.ts
'use server'

export async function createProject(formData: FormData) {
  const name = formData.get('name') as string
  const project = await db.project.create({ data: { name } })
  revalidatePath('/projects')
  return { success: true, project }
}

// app/projects/new/page.tsx
import { createProject } from '@/app/actions'

export default function NewProjectPage() {
  return (
    <form action={createProject}>
      <input name="name" required />
      <button type="submit">Create</button>
    </form>
  )
}

4. Streaming with Suspense

// app/dashboard/page.tsx
import { Suspense } from 'react'

export default function DashboardPage() {
  return (
    <div>
      <Suspense fallback={<ProjectsSkeleton />}>
        <ProjectsAsync />
      </Suspense>
      <Suspense fallback={<UsersSkeleton />}>
        <UsersAsync />
      </Suspense>
    </div>
  )
}

async function ProjectsAsync() {
  const projects = await fetchProjects() // Slow query
  return <ProjectList projects={projects} />
}

5. Dynamic Metadata

// app/blog/[slug]/page.tsx
import type { Metadata } from 'next'

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>
}): Promise<Metadata> {
  const { slug } = await params
  const post = await fetchPost(slug)

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [post.coverImage],
    },
  }
}

Best Practices for Quetrex

1. Default to Server Components

// ✅ DO: Server Component (default)
export default async function ProjectsPage() {
  const projects = await fetchProjects()
  return <ProjectList projects={projects} />
}

// ❌ DON'T: Client Component when not needed
'use client'
export default function ProjectsPage() {
  const [projects, setProjects] = useState([])
  useEffect(() => {
    fetchProjects().then(setProjects)
  }, [])
  return <ProjectList projects={projects} />
}

2. Use Proper Cache Strategy

// Static content (cached forever)
const categories = await fetch('https://api.example.com/categories', {
  cache: 'force-cache',
}).then(r => r.json())

// Dynamic