name	app-router-helper
description	Implement Next.js App Router patterns including Server Components, Client Components, layouts, route organization, and data fetching. Use when building with App Router, organizing routes, or implementing modern Next.js patterns. Trigger words include "App Router", "Server Component", "Client Component", "layout", "app directory".

App Router Helper

Name: app-router-helper
Author: armanzeroeight

Implement Next.js App Router patterns for modern React applications.

Quick Start

App Router (Next.js 13+) uses file-system routing in the app/ directory with Server Components by default.

Key concepts:

Server Components (default): Render on server, reduce bundle size
Client Components ('use client'): Interactive, use hooks
Layouts: Shared UI across routes
Loading/Error: Automatic UI states

Instructions

Step 1: Understand File Structure

Basic structure:

app/
├── layout.tsx          # Root layout (required)
├── page.tsx            # Home page (/)
├── loading.tsx         # Loading UI
├── error.tsx           # Error UI
├── not-found.tsx       # 404 page
└── about/
    └── page.tsx        # About page (/about)

Special files:

layout.tsx: Shared UI, doesn't re-render
page.tsx: Unique UI for route
loading.tsx: Loading state (Suspense boundary)
error.tsx: Error boundary
template.tsx: Re-renders on navigation
route.ts: API endpoint

Step 2: Create Layouts

Root layout (required):

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <Header />
        {children}
        <Footer />
      </body>
    </html>
  );
}

Nested layouts:

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div>
      <Sidebar />
      <main>{children}</main>
    </div>
  );
}

Layouts persist across navigation and don't re-render.

Step 3: Server vs Client Components

Server Component (default):

// app/products/page.tsx
// No 'use client' = Server Component

async function ProductsPage() {
  // Can fetch data directly
  const products = await db.products.findMany();
  
  return (
    <div>
      {products.map(p => (
        <ProductCard key={p.id} product={p} />
      ))}
    </div>
  );
}

export default ProductsPage;

Client Component:

// app/components/AddToCart.tsx
'use client';

import { useState } from 'react';

export function AddToCart({ productId }: { productId: string }) {
  const [count, setCount] = useState(1);
  
  const handleAdd = () => {
    // Client-side logic
    addToCart(productId, count);
  };
  
  return (
    <div>
      <button onClick={() => setCount(count - 1)}>-</button>
      <span>{count}</span>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={handleAdd}>Add to Cart</button>
    </div>
  );
}

When to use 'use client':

Event handlers (onClick, onChange)
React hooks (useState, useEffect, useContext)
Browser APIs (localStorage, window)
Third-party libraries requiring client

Step 4: Implement Data Fetching

Server Component data fetching:

// app/posts/page.tsx
async function PostsPage() {
  // Fetch in Server Component
  const posts = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 } // Cache for 1 hour
  }).then(res => res.json());
  
  return <PostList posts={posts} />;
}

Parallel data fetching:

async function Page() {
  // Fetch in parallel
  const [user, posts] = await Promise.all([
    fetchUser(),
    fetchPosts(),
  ]);
  
  return (
    <div>
      <UserProfile user={user} />
      <PostList posts={posts} />
    </div>
  );
}

Sequential data fetching:

async function Page() {
  const user = await fetchUser();
  const posts = await fetchUserPosts(user.id); // Depends on user
  
  return <div>...</div>;
}

Step 5: Organize Routes

Route groups (don't affect URL):

app/
├── (marketing)/
│   ├── layout.tsx      # Marketing layout
│   ├── about/
│   │   └── page.tsx    # /about
│   └── contact/
│       └── page.tsx    # /contact
└── (shop)/
    ├── layout.tsx      # Shop layout
    └── products/
        └── page.tsx    # /products

Dynamic routes:

app/
└── products/
    └── [id]/
        └── page.tsx    # /products/123

// app/products/[id]/page.tsx
export default function ProductPage({
  params,
}: {
  params: { id: string }
}) {
  return <div>Product {params.id}</div>;
}

Catch-all routes:

app/
└── docs/
    └── [...slug]/
        └── page.tsx    # /docs/a, /docs/a/b, /docs/a/b/c

Step 6: Handle Loading and Errors

Loading UI:

// app/dashboard/loading.tsx
export default function Loading() {
  return <div>Loading dashboard...</div>;
}

Error handling:

// app/dashboard/error.tsx
'use client'; // Error components must be Client Components

export default function Error({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

Not found:

// app/not-found.tsx
export default function NotFound() {
  return <div>404 - Page Not Found</div>;
}

Common Patterns

Streaming with Suspense

import { Suspense } from 'react';

export default function Page() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<Skeleton />}>
        <SlowComponent />
      </Suspense>
      <FastComponent />
    </div>
  );
}

Parallel Routes

app/
└── dashboard/
    ├── layout.tsx
    ├── @analytics/
    │   └── page.tsx
    ├── @team/
    │   └── page.tsx
    └── page.tsx

// app/dashboard/layout.tsx
export default function Layout({
  children,
  analytics,
  team,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  team: React.ReactNode;
}) {
  return (
    <div>
      {children}
      <div className="grid">
        {analytics}
        {team}
      </div>
    </div>
  );
}

Intercepting Routes

app/
└── photos/
    ├── [id]/
    │   └── page.tsx
    └── (.)[id]/
        └── page.tsx    # Intercepts /photos/[id]

Metadata

// app/products/[id]/page.tsx
import { Metadata } from 'next';

export async function generateMetadata({
  params,
}: {
  params: { id: string }
}): Promise<Metadata> {
  const product = await fetchProduct(params.id);
  
  return {
    title: product.name,
    description: product.description,
    openGraph: {
      images: [product.image],
    },
  };
}

API Routes

// app/api/products/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const products = await db.products.findMany();
  return NextResponse.json(products);
}

export async function POST(request: Request) {
  const body = await request.json();
  const product = await db.products.create({ data: body });
  return NextResponse.json(product, { status: 201 });
}

Dynamic API routes:

// app/api/products/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const product = await db.products.findUnique({
    where: { id: params.id }
  });
  return NextResponse.json(product);
}

Advanced

For detailed patterns:

Server Components - Deep dive into Server Components
Client Components - Client Component patterns
Data Fetching - Advanced data fetching strategies

Troubleshooting

"use client" not working:

Must be at top of file
Check for Server Component imports
Verify no async in Client Components

Data not updating:

Check cache configuration
Use revalidatePath or revalidateTag
Verify fetch cache settings

Layout not applying:

Ensure layout.tsx exists
Check file naming (must be exact)
Verify export default

Hydration errors:

Server and client HTML must match
Avoid using browser APIs in Server Components
Check for dynamic content (dates, random)

Best Practices

Default to Server Components: Only use 'use client' when needed
Fetch data where needed: Co-locate data fetching with components
Use layouts: Share UI and avoid re-renders
Implement loading states: Use loading.tsx and Suspense
Handle errors: Add error.tsx boundaries
Optimize metadata: Use generateMetadata for SEO
Stream content: Use Suspense for better UX
Type everything: Use TypeScript for params and props

app-router-helper

Install Skill

SKILL.md