Skill

Pass

Audit score 90

nextjs-app-router-fundamentals

wsimmonds/claude-nextjs-skills

Guide for Next.js App Router (13+): migration, layouts, routing, and metadata handling.

What is nextjs-app-router-fundamentals?

Comprehensive reference for working with Next.js App Router in version 13 and later. Use this skill when migrating from the legacy Pages Router, creating new App Router applications, building layouts, implementing routing patterns, or handling metadata and SEO. Covers file conventions, migration steps, TypeScript patterns, and common pitfalls.

Migrate Pages Router applications to App Router with step-by-step guidance
Create and nest layouts that preserve state across navigation
Implement dynamic routes, catch-all routes, and route groups
Handle static and dynamic metadata for SEO optimization
Enforce strict TypeScript typing (no `any` type allowed)
Understand file conventions (page.tsx, layout.tsx, loading.tsx, error.tsx, route.ts)

How to install nextjs-app-router-fundamentals

npx skills add https://github.com/wsimmonds/claude-nextjs-skills --skill nextjs-app-router-fundamentals

Prerequisites

Next.js 13 or later installed
Familiarity with React and TypeScript
Understanding of file-based routing concepts

Claude Code

Cursor

Windsurf

Cline

How to use nextjs-app-router-fundamentals

1.Examine your current Pages Router structure (pages/, _app.tsx, _document.tsx)
2.Create app/layout.tsx as the root layout with html and body tags
3.Migrate pages from pages/ directory to app/ directory structure
4.Convert metadata from next/head to metadata exports
5.Replace anchor tags with next/link components
6.Update dynamic routes to use [slug] folder syntax
7.Test routing and metadata before removing pages/ directory

Use cases

Good for

Upgrading a Next.js 12 application to Next.js 13+ App Router
Building a new Next.js 13+ application from scratch with proper routing structure
Creating nested layouts for blog sections, admin panels, or marketing sites
Implementing dynamic routes for product pages, blog posts, or user profiles
Setting up metadata and OpenGraph tags for SEO and social sharing

Who it's for

Next.js developers migrating from Pages Router to App Router
Full-stack developers building new Next.js 13+ applications
Teams adopting modern Next.js patterns and conventions
Developers implementing SEO and metadata management in Next.js

nextjs-app-router-fundamentals FAQ

Do I need to migrate all pages at once?

No. You can migrate incrementally. Keep pages/api/ for API routes while migrating page routes to App Router, or migrate one section at a time.

What's the difference between layout.tsx and template.tsx?

Layouts preserve state and don't re-render on navigation. Templates re-render on every navigation. Use layouts for persistent UI (headers, sidebars) and templates when you need fresh state on each route.

How do I handle global providers (Redux, Theme, etc.)?

Wrap your children in the root layout.tsx. Create a separate client component with 'use client' directive if needed, then use it in layout.tsx to wrap {children}.

Can I colocate components and tests in the app/ directory?

Yes. Only page.tsx and route.ts files create public routes. Other files (components, utils, tests) can be colocated and won't be routable.

Why does the skill enforce no `any` type in TypeScript?

The codebase has @typescript-eslint/no-explicit-any enabled, which causes build failures if `any` is used. Use proper types like React.FormEvent, React.ChangeEvent, or specific interfaces instead.

Full instructions (SKILL.md)

Source of truth, from wsimmonds/claude-nextjs-skills.

name: nextjs-app-router-fundamentals description: Guide for working with Next.js App Router (Next.js 13+). Use when migrating from Pages Router to App Router, creating layouts, implementing routing, handling metadata, or building Next.js 13+ applications. Activates for App Router migration, layout creation, routing patterns, or Next.js 13+ development tasks. allowed-tools: Read, Write, Edit, Glob, Grep, Bash

Next.js App Router Fundamentals

Overview

Provide comprehensive guidance for Next.js App Router (Next.js 13+), covering migration from Pages Router, file-based routing conventions, layouts, metadata handling, and modern Next.js patterns.

TypeScript: NEVER Use `any` Type

CRITICAL RULE: This codebase has @typescript-eslint/no-explicit-any enabled. Using any will cause build failures.

❌ WRONG:

function handleSubmit(e: any) { ... }
const data: any[] = [];

✅ CORRECT:

function handleSubmit(e: React.FormEvent<HTMLFormElement>) { ... }
const data: string[] = [];

Common Next.js Type Patterns

// Page props
function Page({ params }: { params: { slug: string } }) { ... }
function Page({ searchParams }: { searchParams: { [key: string]: string | string[] | undefined } }) { ... }

// Form events
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => { ... }
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => { ... }

// Server actions
async function myAction(formData: FormData) { ... }

When to Use This Skill

Use this skill when:

Migrating from Pages Router (pages/ directory) to App Router (app/ directory)
Creating Next.js 13+ applications from scratch
Working with layouts, templates, and nested routing
Implementing metadata and SEO optimizations
Building with App Router routing conventions
Handling route groups, parallel routes, or intercepting routes basics

Core Concepts

App Router vs Pages Router

Pages Router (Legacy - Next.js 12 and earlier):

pages/
├── index.tsx              # Route: /
├── about.tsx              # Route: /about
├── _app.tsx               # Custom App component
├── _document.tsx          # Custom Document component
└── api/                   # API routes
    └── hello.ts           # API endpoint: /api/hello

App Router (Modern - Next.js 13+):

app/
├── layout.tsx             # Root layout (required)
├── page.tsx               # Route: /
├── about/                 # Route: /about
│   └── page.tsx
├── blog/
│   ├── layout.tsx         # Nested layout
│   └── [slug]/
│       └── page.tsx       # Dynamic route: /blog/:slug
└── api/                   # Route handlers
    └── hello/
        └── route.ts       # API endpoint: /api/hello

File Conventions

Special Files in App Router:

layout.tsx - Shared UI for a segment and its children (preserves state, doesn't re-render)
page.tsx - Unique UI for a route, makes route publicly accessible
loading.tsx - Loading UI with React Suspense
error.tsx - Error UI with Error Boundaries
not-found.tsx - 404 UI
template.tsx - Similar to layout but re-renders on navigation
route.ts - API endpoints (Route Handlers)

Colocation:

Components, tests, and other files can be colocated in app/
Only page.tsx and route.ts files create public routes
Other files (components, utils, tests) are NOT routable

Migration Guide: Pages Router to App Router

Step 1: Understand the Current Structure

Examine existing Pages Router setup:

Read pages/ directory structure
Identify _app.tsx - handles global state, layouts, providers
Identify _document.tsx - customizes HTML structure
Note metadata usage (next/head, <Head> component)
List all routes and dynamic segments

Step 2: Create Root Layout

Create app/layout.tsx - REQUIRED for all App Router applications:

// app/layout.tsx
export const metadata = {
  title: 'My App',
  description: 'App description',
};

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

Migration Notes:

Move _document.tsx HTML structure to layout.tsx
Move _app.tsx global providers/wrappers to layout.tsx
Convert <Head> metadata to metadata export
The root layout MUST include <html> and <body> tags

Step 3: Migrate Pages to Routes

Simple Page Migration:

// Before: pages/index.tsx
import Head from 'next/head';

export default function Home() {
  return (
    <>
      <Head>
        <title>Home Page</title>
      </Head>
      <main>
        <h1>Welcome</h1>
      </main>
    </>
  );
}

// After: app/page.tsx
export default function Home() {
  return (
    <main>
      <h1>Welcome</h1>
    </main>
  );
}

// Metadata moved to layout.tsx or exported here
export const metadata = {
  title: 'Home Page',
};

Nested Route Migration:

// Before: pages/blog/[slug].tsx
export default function BlogPost() { ... }

// After: app/blog/[slug]/page.tsx
export default function BlogPost() { ... }

Step 4: Update Navigation

Replace anchor tags with Next.js Link:

// Before (incorrect in App Router)
<a href="/about">About</a>

// After (correct)
import Link from 'next/link';
<Link href="/about">About</Link>

Step 5: Clean Up Pages Directory

After migration:

Remove all page files from pages/ directory
Keep pages/api/ if you're not migrating API routes yet
Remove _app.tsx and _document.tsx (functionality moved to layout)
Optionally delete empty pages/ directory

Metadata Handling

Static Metadata

// app/page.tsx or app/layout.tsx
import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'My Page',
  description: 'Page description',
  keywords: ['nextjs', 'react'],
  openGraph: {
    title: 'My Page',
    description: 'Page description',
    images: ['/og-image.jpg'],
  },
};

Dynamic Metadata

// app/blog/[slug]/page.tsx
export async function generateMetadata({
  params
}: {
  params: { slug: string }
}): Promise<Metadata> {
  const post = await getPost(params.slug);

  return {
    title: post.title,
    description: post.excerpt,
  };
}

Layouts and Nesting

Creating Nested Layouts

// app/layout.tsx - Root layout
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Header />
        {children}
        <Footer />
      </body>
    </html>
  );
}

// app/blog/layout.tsx - Blog layout
export default function BlogLayout({ children }) {
  return (
    <div>
      <BlogSidebar />
      <main>{children}</main>
    </div>
  );
}

Layout Behavior:

Layouts preserve state across navigation
Layouts don't re-render on route changes
Parent layouts wrap child layouts
Root layout is required and wraps entire app

Routing Patterns

Dynamic Routes

// app/blog/[slug]/page.tsx
export default function BlogPost({
  params
}: {
  params: { slug: string }
}) {
  return <article>Post: {params.slug}</article>;
}

Catch-All Routes

// app/shop/[...slug]/page.tsx - Matches /shop/a, /shop/a/b, etc.
export default function Shop({
  params
}: {
  params: { slug: string[] }
}) {
  return <div>Path: {params.slug.join('/')}</div>;
}

Optional Catch-All

// app/shop/[[...slug]]/page.tsx - Matches /shop AND /shop/a, /shop/a/b

Route Groups

Group routes without affecting URL:

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

Common Migration Pitfalls

Pitfall 1: Forgetting Root Layout HTML Tags

Wrong:

export default function RootLayout({ children }) {
  return <div>{children}</div>; // Missing <html> and <body>
}

Correct:

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

Pitfall 2: Using `next/head` in App Router

Wrong:

import Head from 'next/head';

export default function Page() {
  return (
    <>
      <Head><title>Title</title></Head>
      <main>Content</main>
    </>
  );
}

Correct:

export const metadata = { title: 'Title' };

export default function Page() {
  return <main>Content</main>;
}

Pitfall 3: Not Removing Pages Directory

After migrating routes, remove the old pages/ directory files to avoid confusion. The build will fail if you have conflicting routes.

Pitfall 4: Missing `page.tsx` Files

Routes are NOT accessible without a page.tsx file. Layouts alone don't create routes.

app/
├── blog/
│   ├── layout.tsx   # NOT a route
│   └── page.tsx     # This makes /blog accessible

Pitfall 5: Incorrect Link Usage

Wrong:

<a href="/about">About</a>  // Works but causes full page reload

Correct:

import Link from 'next/link';
<Link href="/about">About</Link>  // Client-side navigation

Server Components vs Client Components

Default: Server Components

All components in app/ are Server Components by default:

// app/page.tsx - Server Component (default)
export default async function Page() {
  const data = await fetch('https://api.example.com/data');
  const json = await data.json();

  return <div>{json.title}</div>;
}

Benefits:

Can use async/await directly
Direct database/API access
Zero client-side JavaScript
Automatic code splitting

Client Components

Use 'use client' directive when you need:

Interactive elements (onClick, onChange, etc.)
React hooks (useState, useEffect, useContext, etc.)
Browser APIs (window, localStorage, etc.)
Event listeners

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

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

Data Fetching Patterns

Server Component Data Fetching

// app/posts/page.tsx
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 } // Revalidate every hour
  });
  return res.json();
}

export default async function PostsPage() {
  const posts = await getPosts();

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

Parallel Data Fetching

export default async function Page() {
  // Fetch in parallel
  const [posts, users] = await Promise.all([
    fetch('https://api.example.com/posts').then(r => r.json()),
    fetch('https://api.example.com/users').then(r => r.json()),
  ]);

  return (/* render */);
}

Static Site Generation with generateStaticParams

Overview

generateStaticParams is the App Router equivalent of getStaticPaths from the Pages Router. It generates static pages at build time for dynamic routes.

Basic Usage

// app/blog/[id]/page.tsx
export async function generateStaticParams() {
  // Return array of params to pre-render
  return [
    { id: '1' },
    { id: '2' },
    { id: '3' },
  ];
}

export default function BlogPost({
  params
}: {
  params: { id: string }
}) {
  return <article>Blog post {params.id}</article>;
}

Key Points:

Returns an array of objects with route parameter keys
Each object represents one page to pre-render at build time
Function must be exported and named generateStaticParams
Works ONLY in Server Components (no 'use client' directive)
Replaces Pages Router's getStaticPaths

Fetching Data for Static Params

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts').then(r => r.json());

  return posts.map((post: { slug: string }) => ({
    slug: post.slug,
  }));
}

export default async function BlogPost({
  params
}: {
  params: { slug: string }
}) {
  const post = await fetch(`https://api.example.com/posts/${params.slug}`).then(r => r.json());

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  );
}

Multiple Dynamic Segments

// app/products/[category]/[id]/page.tsx
export async function generateStaticParams() {
  const categories = await getCategories();

  const params = [];
  for (const category of categories) {
    const products = await getProducts(category.slug);
    for (const product of products) {
      params.push({
        category: category.slug,
        id: product.id,
      });
    }
  }

  return params;
}

export default function ProductPage({
  params
}: {
  params: { category: string; id: string }
}) {
  return <div>Category: {params.category}, Product: {params.id}</div>;
}

Dynamic Behavior Configuration

// app/blog/[id]/page.tsx
export async function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }];
}

// Control behavior for non-pre-rendered paths
export const dynamicParams = true; // default - allows runtime generation
// export const dynamicParams = false; // returns 404 for non-pre-rendered paths

export default function BlogPost({
  params
}: {
  params: { id: string }
}) {
  return <article>Post {params.id}</article>;
}

Options:

dynamicParams = true (default): Non-pre-rendered paths generated on-demand
dynamicParams = false: Non-pre-rendered paths return 404

Common Patterns

Pattern 1: Simple ID-based routes

export async function generateStaticParams() {
  return [
    { id: '1' },
    { id: '2' },
    { id: '3' },
  ];
}

Pattern 2: Fetch from API

export async function generateStaticParams() {
  const items = await fetch('https://api.example.com/items').then(r => r.json());
  return items.map(item => ({ id: item.id }));
}

Pattern 3: Database query

export async function generateStaticParams() {
  const posts = await db.post.findMany();
  return posts.map(post => ({ slug: post.slug }));
}

Migration from Pages Router

Before (Pages Router):

// pages/blog/[id].tsx
export async function getStaticPaths() {
  return {
    paths: [
      { params: { id: '1' } },
      { params: { id: '2' } },
    ],
    fallback: false,
  };
}

export async function getStaticProps({ params }) {
  return { props: { id: params.id } };
}

After (App Router):

// app/blog/[id]/page.tsx
export async function generateStaticParams() {
  return [
    { id: '1' },
    { id: '2' },
  ];
}

export const dynamicParams = false; // equivalent to fallback: false

export default function BlogPost({ params }: { params: { id: string } }) {
  return <div>Post {params.id}</div>;
}

Common Mistakes to Avoid

❌ Wrong: Using 'use client'

'use client'; // ERROR! generateStaticParams only works in Server Components

export async function generateStaticParams() {
  return [{ id: '1' }];
}

❌ Wrong: Using Pages Router pattern

export async function getStaticPaths() { // Wrong API!
  return { paths: [...], fallback: false };
}

❌ Wrong: Missing export keyword

async function generateStaticParams() { // Must be exported!
  return [{ id: '1' }];
}

✅ Correct: Clean Server Component

// app/blog/[id]/page.tsx
// No 'use client' directive

export async function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }];
}

export default function Page({ params }: { params: { id: string } }) {
  return <div>Post {params.id}</div>;
}

CRITICAL IMPLEMENTATION NOTE:

When asked to "write" or "implement" generateStaticParams:

DO use the Edit or Write tool to modify the actual file
DO add the function to the existing page.tsx file
DO remove any TODO comments about generateStaticParams
DON'T just output code in markdown - actually implement it
DON'T show code without writing it to the file

Testing and Validation

When migrating or building with App Router, verify:

Structure:
- app/ directory exists
- Root layout.tsx exists with <html> and <body>
- Each route has a page.tsx file
Metadata:
- No next/head imports in App Router
- Metadata exported from pages or layouts
- Metadata properly typed with Metadata type
Navigation:
- Using Link component from next/link
- Not using plain <a> tags for internal navigation
Cleanup:
- No remaining page files in pages/ directory
- _app.tsx and _document.tsx removed
- Old metadata patterns removed

Quick Reference

File Structure Mapping

Pages Router	App Router	Purpose
`pages/index.tsx`	`app/page.tsx`	Home route
`pages/about.tsx`	`app/about/page.tsx`	About route
`pages/[id].tsx`	`app/[id]/page.tsx`	Dynamic route
`pages/_app.tsx`	`app/layout.tsx`	Global layout
`pages/_document.tsx`	`app/layout.tsx`	HTML structure
`pages/api/hello.ts`	`app/api/hello/route.ts`	API route

Common Commands

# Create new Next.js app with App Router
npx create-next-app@latest my-app

# Run development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

Additional Resources

For more advanced routing patterns (parallel routes, intercepting routes, route handlers), refer to the nextjs-advanced-routing skill.

For Server vs Client component best practices and anti-patterns, refer to the nextjs-server-client-components and nextjs-anti-patterns skills.

Related skills

More from wsimmonds/claude-nextjs-skills and the wider catalog.

wechat-article-search

wuchubuzai2018/expert-skills-hub

Search WeChat public account articles by keyword and retrieve titles, summaries, publish dates, sources, and links.

1.4k installs

douyin

xiaoyiv/douyin-skill

Download Douyin videos and extract metadata from short links and full URLs.

4.3k installs

develop-userscripts

xixu-me/skills

Build, debug, and publish Tampermonkey and ScriptCat userscripts with proper metadata, permissions, and runtime selection.

206k installs

github-actions-docs

xixu-me/skills

Ground GitHub Actions questions in official documentation with exact links and docs-backed YAML guidance.

257k installs

openclaw-secure-linux-cloud

xixu-me/skills

Secure self-hosted OpenClaw on Linux cloud servers with conservative defaults: loopback binding, SSH tunneling, token auth, and minimal tool permissions.

253k installs

opensource-guide-coach

xixu-me/skills

Coach for open source project decisions using official Open Source Guides as a framework.

252k installsAudited

nextjs-app-router-fundamentals

What is nextjs-app-router-fundamentals?

How to install nextjs-app-router-fundamentals

How to use nextjs-app-router-fundamentals

Use cases

nextjs-app-router-fundamentals FAQ

Next.js App Router Fundamentals

Overview

TypeScript: NEVER Use any Type

Common Next.js Type Patterns

When to Use This Skill

Core Concepts

App Router vs Pages Router

File Conventions

Migration Guide: Pages Router to App Router

Step 1: Understand the Current Structure

Step 2: Create Root Layout

Step 3: Migrate Pages to Routes

Step 4: Update Navigation

Step 5: Clean Up Pages Directory

Metadata Handling

Static Metadata

Dynamic Metadata

Layouts and Nesting

Creating Nested Layouts

Routing Patterns

Dynamic Routes

Catch-All Routes

Optional Catch-All

Route Groups

Common Migration Pitfalls

Pitfall 1: Forgetting Root Layout HTML Tags

Pitfall 2: Using next/head in App Router

Pitfall 3: Not Removing Pages Directory

Pitfall 4: Missing page.tsx Files

Pitfall 5: Incorrect Link Usage

Server Components vs Client Components

Default: Server Components

Client Components

Data Fetching Patterns

Server Component Data Fetching

Parallel Data Fetching

Static Site Generation with generateStaticParams

Overview

Basic Usage

Fetching Data for Static Params

Multiple Dynamic Segments

Dynamic Behavior Configuration

Common Patterns

Migration from Pages Router

Common Mistakes to Avoid

Testing and Validation

Quick Reference

File Structure Mapping

Common Commands

Additional Resources

Related skills

wechat-article-search

douyin

develop-userscripts

github-actions-docs

openclaw-secure-linux-cloud

opensource-guide-coach

TypeScript: NEVER Use `any` Type

Pitfall 2: Using `next/head` in App Router

Pitfall 4: Missing `page.tsx` Files