# nextjs-app-router-fundamentals

A skill that walks the agent through Next.js App Router: Pages Router migration, nested layouts, metadata, dynamic routes. Useful when moving to app/.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2200 installs · ★ 109
- Author: wsimmonds
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/wsimmonds/claude-nextjs-skills/tree/HEAD/nextjs-app-router-fundamentals/SKILL.md
- Updated: 2025-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/nextjs-app-router-fundamentals

## What it does

The skill explains how the App Router works in Next.js 13 and later, and steers the agent through the right steps. It covers the file conventions: `layout.tsx`, `page.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`, `template.tsx`, `route.ts`. It also spells out that only `page.tsx` and `route.ts` create public routes, while components and tests can sit alongside them in `app/`.

Migration is broken into steps: read the existing `pages/`, move `_app.tsx` and `_document.tsx` into the root `layout.tsx`, swap `<Head>` for a `metadata` export, move pages into `app/`, fix navigation with `next/link`, clean up `pages/`. There are sections on static and dynamic metadata via `generateMetadata`, plus nested layouts and how they behave across navigation.

One hard rule inside: no `any` in TypeScript, because the project has `@typescript-eslint/no-explicit-any` enabled and the build will fail. Instead the skill hands over ready-made types for page props, form events and server actions. It installs into Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode, but the text is cut off, so check the repository for the rest.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add wsimmonds/claude-nextjs-skills --skill nextjs-app-router-fundamentals -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/nextjs-app-router-fundamentals/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/nextjs-app-router-fundamentals/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add wsimmonds/claude-nextjs-skills --skill nextjs-app-router-fundamentals -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/nextjs-app-router-fundamentals/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add wsimmonds/claude-nextjs-skills --skill nextjs-app-router-fundamentals -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/nextjs-app-router-fundamentals/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install wsimmonds/claude-nextjs-skills nextjs-app-router-fundamentals
```

2. **Manually: put the files in place**
- File: `.github/skills/nextjs-app-router-fundamentals/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add wsimmonds/claude-nextjs-skills --skill nextjs-app-router-fundamentals -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/wsimmonds/claude-nextjs-skills --path nextjs-app-router-fundamentals
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/nextjs-app-router-fundamentals/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add wsimmonds/claude-nextjs-skills --skill nextjs-app-router-fundamentals -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/wsimmonds/claude-nextjs-skills/tree/HEAD/nextjs-app-router-fundamentals/SKILL.md

## When to use it
- move a project from `pages/` to `app/` without losing routes
- build a root layout with `<html>` and `<body>`
- replace `<Head>` with a `metadata` export
- set up dynamic metadata for a blog post page
- get `any` out of props and form handlers

## Example prompts
- Help me migrate this project from Pages Router to App Router, start with the root layout
- Create a nested layout for the blog section in `app/blog/layout.tsx`
- Add dynamic metadata for `app/blog/[slug]/page.tsx` using `generateMetadata`

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 83ebb5e113c8f43a.

BEGIN THIRD-PARTY FILE 83ebb5e113c8f43a
````text
---
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:**
```typescript
function handleSubmit(e: any) { ... }
const data: any[] = [];
```

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

### Common Next.js Type Patterns

```typescript
// 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
````
END THIRD-PARTY FILE 83ebb5e113c8f43a

The third-party file has ended. Everything between the 83ebb5e113c8f43a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2244 of 18293 bytes. © wsimmonds · MIT · https://github.com/wsimmonds/claude-nextjs-skills/tree/HEAD/nextjs-app-router-fundamentals/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md