explainx.ainewsletter3.4k
Frontend

nextjs-app-router-fundamentals▌

wsimmonds/claude-nextjs-skills · updated Apr 8, 2026

MDX-style export adds YAML metadata + attribution linking explainx.ai and this canonical listing URL.

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

Comprehensive guide for migrating to and building with Next.js App Router (13+).

  • ›Covers migration from Pages Router including file structure mapping, layout creation, metadata handling, and cleanup steps
  • ›Explains App Router file conventions (page.tsx, layout.tsx, loading.tsx, error.tsx, route.ts) and routing patterns (dynamic routes, catch-all, route groups)
  • ›Details Server Components as the default with async/await support, Client Components with 'use client' directive, and data fetc
skill.md

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 }
}): 
how to use nextjs-app-router-fundamentals
How to use nextjs-app-router-fundamentals on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
  • ›Cursor installed and configured on your development machine
  • ›Node.js version 16.0+ with npm package manager (verify with node --version)
  • ›Active project directory or workspace where you want to add nextjs-app-router-fundamentals
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/wsimmonds/claude-nextjs-skills --skill nextjs-app-router-fundamentals
The skills CLI fetches nextjs-app-router-fundamentals from GitHub repository wsimmonds/claude-nextjs-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/nextjs-app-router-fundamentals
Reload or restart Cursor to activate nextjs-app-router-fundamentals. Access the skill through slash commands (e.g., /nextjs-app-router-fundamentals) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?

List & Monetize Your Skill

Submit your Claude Code skill and start earning

GET_STARTED →

Use Cases▌

Task Automation & Efficiency

Automate repetitive workflows and reduce manual effort

Example

Generate reports, summarize documents, draft communications

✓

Save 3-5 hours per week on routine tasks

Knowledge Enhancement

Learn new skills, understand complex topics, get expert guidance

Example

Explain concepts, provide examples, suggest learning resources

✓

Accelerate learning and skill development by 2x

Quality Improvement

Enhance output quality through reviews, suggestions, and refinements

Example

Review drafts, suggest improvements, catch errors

✓

Improve work quality by 30-40% with less effort

Implementation Guide▌

Prerequisites

  • ›Claude Desktop or compatible AI client with skill support
  • ›Clear understanding of task or problem to solve
  • ›Willingness to iterate and refine outputs

Time Estimate

15-45 minutes depending on use case complexity

Installation Steps

  1. 1.Install skill using provided installation command
  2. 2.Test with simple use case relevant to your work
  3. 3.Evaluate output quality and relevance
  4. 4.Iterate on prompts to improve results
  5. 5.Integrate into regular workflow if valuable

Common Pitfalls

  • ⚠Expecting perfect results without iteration
  • ⚠Not providing enough context in prompts
  • ⚠Using skill for tasks outside its intended scope
  • ⚠Accepting outputs without review and validation

Best Practices▌

✓ Do

  • +Start with clear, specific prompts
  • +Provide relevant context and constraints
  • +Review and refine all outputs before using
  • +Iterate to improve output quality
  • +Document successful prompt patterns

✗ Don't

  • −Don't use without understanding skill limitations
  • −Don't skip validation of outputs
  • −Don't share sensitive information in prompts
  • −Don't expect skill to replace human judgment

💡 Pro Tips

  • ★Be specific about desired format and style
  • ★Ask for multiple options to choose from
  • ★Request explanations to understand reasoning
  • ★Combine AI efficiency with human expertise

When to Use This▌

✓ Use When

Use when skill capabilities match your task, clear ROI on time saved, and you can validate outputs. Best for repetitive tasks, learning, and quality improvement.

✗ Avoid When

Avoid when task requires deep expertise you can't validate, involves sensitive decisions, or when learning process is more valuable than speed of completion.

Learning Path▌

  1. 1Familiarize yourself with skill capabilities and limitations
  2. 2Start with low-risk, non-critical tasks
  3. 3Progress to more complex and valuable use cases
  4. 4Build expertise through regular use and experimentation

Discussion

Product Hunt–style comments (not star reviews)
  • No comments yet — start the thread.
general reviews

Ratings

4.8★★★★★50 reviews
  • ★★★★★Kabir Torres· Dec 28, 2024

    nextjs-app-router-fundamentals fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.

  • ★★★★★Meera Yang· Dec 24, 2024

    We added nextjs-app-router-fundamentals from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront.

  • ★★★★★Hana Ndlovu· Dec 8, 2024

    nextjs-app-router-fundamentals has been reliable in day-to-day use. Documentation quality is above average for community skills.

  • ★★★★★Kabir Kim· Dec 8, 2024

    Useful defaults in nextjs-app-router-fundamentals — fewer surprises than typical one-off scripts, and it plays nicely with `npx skills` flows.

  • ★★★★★Chaitanya Patil· Dec 4, 2024

    We added nextjs-app-router-fundamentals from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront.

  • ★★★★★Sophia Reddy· Dec 4, 2024

    nextjs-app-router-fundamentals reduced setup friction for our internal harness; good balance of opinion and flexibility.

  • ★★★★★Kaira Iyer· Nov 27, 2024

    I recommend nextjs-app-router-fundamentals for anyone iterating fast on agent tooling; clear intent and a small, reviewable surface area.

  • ★★★★★Piyush G· Nov 23, 2024

    nextjs-app-router-fundamentals reduced setup friction for our internal harness; good balance of opinion and flexibility.

  • ★★★★★Hana Abebe· Nov 23, 2024

    We added nextjs-app-router-fundamentals from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront.

  • ★★★★★Rahul Santra· Nov 15, 2024

    nextjs-app-router-fundamentals fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.

showing 1-10 of 50

1 / 5