# Josiahsiegel Claude Plugin Marketplace Nextjs App Router
> Quick Reference
- Skill: `tomevault-io/josiahsiegel-claude-plugin-marketplace-nextjs-app-router` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/josiahsiegel-claude-plugin-marketplace-nextjs-app-router`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/josiahsiegel-claude-plugin-marketplace-nextjs-app-router/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/josiahsiegel-claude-plugin-marketplace-nextjs-app-router
---
## Quick Reference
| Convention | File | Purpose |
|------------|------|---------|
| Page | `page.tsx` | Route UI (required for route) |
| Layout | `layout.tsx` | Shared UI (persists across navigations) |
| Loading | `loading.tsx` | Loading UI with Suspense |
| Error | `error.tsx` | Error boundary (must be 'use client') |
| Not Found | `not-found.tsx` | 404 UI |
| Template | `template.tsx` | Re-renders on navigation |
| Pattern | Syntax | Example |
|---------|--------|---------|
| Dynamic Route | `[slug]` | `/blog/[slug]/page.tsx` |
| Catch-all | `[...slug]` | `/docs/[...slug]/page.tsx` |
| Optional Catch-all | `[[...slug]]` | `/shop/[[...slug]]/page.tsx` |
| Route Group | `(name)` | `/(marketing)/about/page.tsx` |
| Parallel Route | `@slot` | `/@analytics/page.tsx` |
## When to Use This Skill
Use for **App Router fundamentals**:
- Setting up new Next.js 15 projects with App Router
- Understanding file-based routing conventions
- Creating layouts that persist across navigation
- Implementing loading states and error boundaries
- Organizing routes with groups
**Related skills:**
- For data fetching: see `nextjs-data-fetching`
- For advanced routing: see `nextjs-routing-advanced`
- For caching strategies: see `nextjs-caching`
---
# Next.js App Router Fundamentals
## Project Structure
### App Directory
```
app/
├── layout.tsx # Root layout (required)
├── page.tsx # Home page (/)
├── loading.tsx # Loading UI
├── error.tsx # Error boundary
├── not-found.tsx # 404 page
├── global-error.tsx # Global error boundary
├── template.tsx # Re-renders on navigation
│
├── (marketing)/ # Route group (no URL impact)
│ ├── about/
│ │ └── page.tsx # /about
│ └── contact/
│ └── page.tsx # /contact
│
├── dashboard/
│ ├── layout.tsx # Dashboard layout
│ ├── page.tsx # /dashboard
│ ├── loading.tsx # Dashboard loading
│ ├── @analytics/ # Parallel route
│ │ └── page.tsx
│ ├── @team/ # Parallel route
│ │ └── page.tsx
│ └── settings/
│ └── page.tsx # /dashboard/settings
│
├── blog/
│ ├── page.tsx # /blog
│ └── [slug]/ # Dynamic route
│ ├── page.tsx # /blog/:slug
│ └── opengraph-image.tsx
│
├── products/
│ └── [...slug]/ # Catch-all route
│ └── page.tsx # /products/*
│
├── shop/
│ └── [[...slug]]/ # Optional catch-all
│ └── page.tsx # /shop or /shop/*
│
└── api/
└── users/
└── route.ts # API route handler
```
## Layouts
### Root Layout (Required)
```tsx
// app/layout.tsx
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import './globals.css';
const inter = Inter({ subsets: ['latin'] });
export const metadata: Metadata = {
title: {
template: '%s | My App',
default: 'My App',
},
description: 'My application description',
};
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
### Nested Layout
```tsx
// app/dashboard/layout.tsx
import { Sidebar } from '@/components/sidebar';
export default function DashboardLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
);
}
```
### Layout with Parallel Routes
```tsx
// app/dashboard/layout.tsx
export default function DashboardLayout({
children,
analytics,
team,
}: {
children: React.ReactNode;
analytics: React.ReactNode;
team: React.ReactNode;
}) {
return (
{children}
{analytics}
{team}
);
}
```
## Pages
### Basic Page
```tsx
// app/page.tsx
export default function HomePage() {
return (
Welcome to My App
This is the home page.
);
}
```
### Async Server Component Page
```tsx
// app/posts/page.tsx
import { db } from '@/lib/db';
async function getPosts() {
return db.posts.findMany({
orderBy: { createdAt: 'desc' },
});
}
export default async function PostsPage() {
const posts = await getPosts();
return (
);
}
```
### Dynamic Route Page
```tsx
// app/posts/[slug]/page.tsx
import { notFound } from 'next/navigation';
import { db } from '@/lib/db';
interface PageProps {
params: Promise<{ slug: string }>;
}
export async function generateMetadata({ params }: PageProps) {
const { slug } = await params;
const post = await db.posts.findUnique({ where: { slug } });
if (!post) {
return { title: 'Post Not Found' };
}
return {
title: post.title,
description: post.excerpt,
};
}
export async function generateStaticParams() {
const posts = await db.posts.findMany({ select: { slug: true } });
return posts.map((post) => ({ slug: post.slug }));
}
export default async function PostPage({ params }: PageProps) {
const { slug } = await params;
const post = await db.posts.findUnique({ where: { slug } });
if (!post) {
notFound();
}
return (
{post.title}
);
}
```
## Loading UI
### Loading Component
```tsx
// app/dashboard/loading.tsx
export default function Loading() {
return (
);
}
```
### Skeleton Loading
```tsx
// app/posts/loading.tsx
export default function PostsLoading() {
return (
{Array.from({ length: 5 }).map((_, i) => (
))}
Something went wrong!
{error.message}
reset()}>Try again
);
}
```
### Global Error Boundary
```tsx
// app/global-error.tsx
'use client';
export default function GlobalError({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
return (
Something went wrong!
reset()}>Try again
);
}
```
### Not Found Page
```tsx
// app/not-found.tsx
import Link from 'next/link';
export default function NotFound() {
return (
Page Not Found
Could not find the requested resource.
Return Home
);
}
```
### Triggering Not Found
```tsx
// app/posts/[slug]/page.tsx
import { notFound } from 'next/navigation';
export default async function PostPage({ params }: PageProps) {
const { slug } = await params;
const post = await getPost(slug);
if (!post) {
notFound();
}
return {/* ... */} ;
}
```
## Metadata
### Static Metadata
```tsx
// app/about/page.tsx
import type { Metadata } from 'next';
export const metadata: Metadata = {
title: 'About Us',
description: 'Learn more about our company',
openGraph: {
title: 'About Us',
description: 'Learn more about our company',
images: ['/og-about.jpg'],
},
};
export default function AboutPage() {
return About content
;
}
```
### Dynamic Metadata
```tsx
// app/products/[id]/page.tsx
import type { Metadata, ResolvingMetadata } from 'next';
interface PageProps {
params: Promise<{ id: string }>;
}
export async function generateMetadata(
{ params }: PageProps,
parent: ResolvingMetadata
): Promise {
const { id } = await params;
const product = await getProduct(id);
const previousImages = (await parent).openGraph?.images || [];
return {
title: product.name,
description: product.description,
openGraph: {
images: [product.image, ...previousImages],
},
};
}
```
### Metadata Template
```tsx
// app/layout.tsx
export const metadata: Metadata = {
title: {
template: '%s | My Store',
default: 'My Store',
},
metadataBase: new URL('https://mystore.com'),
};
// app/products/page.tsx
export const metadata: Metadata = {
title: 'Products', // Results in "Products | My Store"
};
```
## Templates vs Layouts
```tsx
// app/dashboard/template.tsx
// Template re-mounts on navigation (state resets)
export default function DashboardTemplate({
children,
}: {
children: React.ReactNode;
}) {
return (
Dashboard Navigation
{children}
);
}
```
## Route Groups
```tsx
// (marketing)/about/page.tsx → /about
// (marketing)/contact/page.tsx → /contact
// (shop)/products/page.tsx → /products
// (shop)/cart/page.tsx → /cart
// Different layouts for different sections
// app/(marketing)/layout.tsx - Marketing layout
// app/(shop)/layout.tsx - Shop layout
```
## Client Components
```tsx
// components/Counter.tsx
'use client';
import { useState } from 'react';
export function Counter() {
const [count, setCount] = useState(0);
return (
Count: {count}
setCount((c) => c + 1)}>Increment
);
}
```
### Composing Server and Client Components
```tsx
// app/page.tsx (Server Component)
import { Counter } from '@/components/Counter';
import { db } from '@/lib/db';
export default async function Page() {
const initialData = await db.getData();
return (
Server rendered title
);
}
```
### useRouter Hook
```tsx
'use client';
import { useRouter } from 'next/navigation';
export function NavigateButton() {
const router = useRouter();
return (
router.push('/dashboard')}>
Go to Dashboard
);
}
```
### usePathname and useSearchParams
```tsx
'use client';
import { usePathname, useSearchParams } from 'next/navigation';
export function CurrentPath() {
const pathname = usePathname();
const searchParams = useSearchParams();
const query = searchParams.get('q');
return (
Current path: {pathname}
{query &&
Search query: {query}
}
);
}
```
## Best Practices
| Practice | Description |
|----------|-------------|
| Default to Server Components | Only use 'use client' when needed |
| Colocate related files | Keep page, loading, error together |
| Use route groups | Organize without affecting URL |
| Implement loading states | Use loading.tsx or Suspense |
| Handle errors gracefully | Use error.tsx boundaries |
| Optimize metadata | Use generateMetadata for dynamic pages |
---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/josiahsiegel) — claim your Tome and manage your conversions.