>_

nextjs

Guide for implementing Next.js - a React framework for production with server-side rendering, static generation, and modern web features. Use when building Next.js applications, implementing App Router, working with server components, data fetching, routing, or optimizing performance.

$ Instalar

git clone https://github.com/timelessco/recollect /tmp/recollect && cp -r /tmp/recollect/.claude/skills/nextjs ~/.claude/skills/recollect

// tip: Run this command in your terminal to install the skill

SKILL.md
View on GitHub โ†’

name: nextjs description: Guide for implementing Next.js - a React framework for production with server-side rendering, static generation, and modern web features. Use when building Next.js applications, implementing App Router, working with server components, data fetching, routing, or optimizing performance. license: MIT version: 1.0.0

Next.js Skill

Next.js is a React framework for building full-stack web applications with server-side rendering, static generation, and powerful optimization features built-in.

Reference

https://nextjs.org/docs/llms.txt

When to Use This Skill

Use this skill when:

  • Building new Next.js applications (v15+)
  • Implementing App Router architecture
  • Working with Server Components and Client Components
  • Setting up routing, layouts, and navigation
  • Implementing data fetching patterns
  • Optimizing images, fonts, and performance
  • Configuring metadata and SEO
  • Setting up API routes and route handlers
  • Migrating from Pages Router to App Router
  • Deploying Next.js applications

Core Concepts

App Router vs Pages Router

App Router (Recommended for v13+):

  • Modern architecture with React Server Components
  • File-system based routing in app/ directory
  • Layouts, loading states, and error boundaries
  • Streaming and Suspense support
  • Nested routing with layouts

Pages Router (Legacy):

  • Traditional page-based routing in pages/ directory
  • Uses getStaticProps, getServerSideProps, getInitialProps
  • Still supported for existing projects

Key Architectural Principles

  1. Server Components by Default: Components in app/ are Server Components unless marked with 'use client'
  2. File-based Routing: File system defines application routes
  3. Nested Layouts: Share UI across routes with layouts
  4. Progressive Enhancement: Works without JavaScript when possible
  5. Automatic Optimization: Images, fonts, scripts auto-optimized

Installation & Setup

Create New Project

npx create-next-app@latest my-app
# or
yarn create next-app my-app
# or
pnpm create next-app my-app
# or
bun create next-app my-app

Interactive Setup Prompts:

  • TypeScript? (Yes recommended)
  • ESLint? (Yes recommended)
  • Tailwind CSS? (Optional)
  • src/ directory? (Optional)
  • App Router? (Yes for new projects)
  • Import alias? (Default: @/*)

Manual Setup

npm install next@latest react@latest react-dom@latest

package.json scripts:

{
	"scripts": {
		"dev": "next dev",
		"build": "next build",
		"start": "next start",
		"lint": "next lint"
	}
}

Project Structure

my-app/
โ”œโ”€โ”€ app/                    # App Router (v13+)
โ”‚   โ”œโ”€โ”€ layout.tsx         # Root layout
โ”‚   โ”œโ”€โ”€ page.tsx           # Home page
โ”‚   โ”œโ”€โ”€ loading.tsx        # Loading UI
โ”‚   โ”œโ”€โ”€ error.tsx          # Error UI
โ”‚   โ”œโ”€โ”€ not-found.tsx      # 404 page
โ”‚   โ”œโ”€โ”€ global.css         # Global styles
โ”‚   โ””โ”€โ”€ [folder]/          # Route segments
โ”œโ”€โ”€ public/                # Static assets
โ”œโ”€โ”€ components/            # React components
โ”œโ”€โ”€ lib/                   # Utility functions
โ”œโ”€โ”€ next.config.js         # Next.js configuration
โ”œโ”€โ”€ package.json
โ””โ”€โ”€ tsconfig.json

Routing

File Conventions

  • page.tsx - Page UI for route
  • layout.tsx - Shared UI for segment and children
  • loading.tsx - Loading UI (wraps page in Suspense)
  • error.tsx - Error UI (wraps page in Error Boundary)
  • not-found.tsx - 404 UI
  • route.ts - API endpoint (Route Handler)
  • template.tsx - Re-rendered layout UI
  • default.tsx - Parallel route fallback

Basic Routing

Static Route:

app/
โ”œโ”€โ”€ page.tsx              โ†’ /
โ”œโ”€โ”€ about/
โ”‚   โ””โ”€โ”€ page.tsx         โ†’ /about
โ””โ”€โ”€ blog/
    โ””โ”€โ”€ page.tsx         โ†’ /blog

Dynamic Route:

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

Catch-all Route:

// app/shop/[...slug]/page.tsx
export default function Shop({ params }: { params: { slug: string[] } }) {
	return <h1>Category: {params.slug.join("/")}</h1>;
}

Optional Catch-all:

// app/docs/[[...slug]]/page.tsx
// Matches /docs, /docs/a, /docs/a/b, etc.

Route Groups

Organize routes without affecting URL:

app/
โ”œโ”€โ”€ (marketing)/          # Group without URL segment
โ”‚   โ”œโ”€โ”€ about/page.tsx   โ†’ /about
โ”‚   โ””โ”€โ”€ blog/page.tsx    โ†’ /blog
โ””โ”€โ”€ (shop)/
    โ”œโ”€โ”€ products/page.tsx โ†’ /products
    โ””โ”€โ”€ cart/page.tsx     โ†’ /cart

Parallel Routes

Render multiple pages in same layout:

app/
โ”œโ”€โ”€ @team/               # Slot
โ”‚   โ””โ”€โ”€ page.tsx
โ”œโ”€โ”€ @analytics/          # Slot
โ”‚   โ””โ”€โ”€ page.tsx
โ””โ”€โ”€ layout.tsx           # Uses both slots

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

Intercepting Routes

Intercept routes to show in modal:

app/
โ”œโ”€โ”€ feed/
โ”‚   โ””โ”€โ”€ page.tsx
โ”œโ”€โ”€ photo/
โ”‚   โ””โ”€โ”€ [id]/
โ”‚       โ””โ”€โ”€ page.tsx
โ””โ”€โ”€ (..)photo/           # Intercepts /photo/[id]
    โ””โ”€โ”€ [id]/
        โ””โ”€โ”€ page.tsx

Layouts

Root Layout (Required)

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

Nested Layouts

// app/dashboard/layout.tsx
export default function DashboardLayout({
	children,
}: {
	children: React.ReactNode;
}) {
	return (
		<section>
			<nav>Dashboard Nav</nav>
			{children}
		</section>
	);
}

Layouts are:

  • Shared across multiple pages
  • Preserve state on navigation
  • Do not re-render on navigation
  • Can fetch data

Server and Client Components

Server Components (Default)

Components in app/ are Server Components by default:

// app/page.tsx (Server Component)
async function getData() {
	const res = await fetch("https://api.example.com/data");
	return res.json();
}

export default async function Page() {
	const data = await getData();
	return <div>{data.title}</div>;
}

Benefits:

  • Fetch data on server
  • Access backend resources directly
  • Keep sensitive data on server
  • Reduce client-side JavaScript
  • Improve initial page load

Limitations:

  • Cannot use hooks (useState, useEffect)
  • Cannot use browser APIs
  • Cannot add event listeners

Client Components

Mark components with 'use client' directive:

// components/counter.tsx
"use client";

import { useState } from "react";

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

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

Use Client Components for:

  • Interactive UI (onClick, onChange)
  • State management (useState, useReducer)
  • Effects (useEffect, useLayoutEffect)
  • Browser APIs (localStorage, navigator)
  • Custom hooks
  • React class components

Composition Pattern

// app/page.tsx (Server Component)
import { ClientComponent } from "./client-component";

export default function Page() {
	return (
		<div>
			<h1>Server-rendered content</h1>
			<ClientComponent />
		</div>
	);
}

Data Fetching

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
	});

	if (!res.ok) {
		throw new Error("Failed to fetch");
	}

	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>
	);
}

Caching Strategies

Force Cache (Default):

fetch("https://api.example.com/data", { cache: "force-cache" });

No Store (Dynamic):

fetch("https://api.example.com/data", { cache: "no-store" });

Revalidate:

fetch("https://api.example.com/data", {
	next: { revalidate: 3600 }, // Seconds
});

Tag-based Revalidation:

fetch("https://api.example.com/data", {
	next: { tags: ["posts"] },
});

// Revalidate elsewhere:
import { revalidateTag } from "next/cache";
revalidateTag("posts");

Parallel Data Fetching

async function getData() {
	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 { posts, users };
}

Sequential Data Fetching

async function getData() {
	const post = await fetch(`https://api.example.com/posts/${id}`).then((r) =>
		r.json(),
	);
	const author = await fetch(
		`https://api.example.com/users/${post.authorId}`,
	).then((r) => r.json());

	return { post, author };
}

Route Handlers (API Routes)

Basic Route Handler

// app/api/hello/route.ts
export async function GET(request: Request) {
	return Response.json({ message: "Hello" });
}

export async function POST(request: Request) {
	const body = await request.json();
	return Response.json({ received: body });
}

Dynamic Route Handler

// app/api/posts/[id]/route.ts
export async function GET(
	request: Request,
	{ params }: { params: { id: string } },
) {
	const post = await getPost(params.id);
	return Response.json(post);
}

export async function DELETE(
	request: Request,
	{ params }: { params: { id: string } },
) {
	await deletePost(params.id);
	return new Response(null, { status: 204 });
}

Request Helpers

export async function GET(request: Request) {
	const { searchParams } = new URL(request.url);
	const id = searchParams.get("id");

	const cookies = request.headers.get("cookie");

	return Response.json({ id });
}

Response Types

// JSON
return Response.json({ data: "value" });

// Text
return new Response("Hello", { headers: { "Content-Type": "text/plain" } });

// Redirect
return Response.redirect("https://example.com");

// Status codes
return new Response("Not Found", { status: 404 });

Navigation

Link Component

import Link from "next/link";

export default function Page() {
	return (
		<>
			<Link href="/about">About</Link>
			<Link href="/blog/post-1">Post 1</Link>
			<Link href={{ pathname: "/blog/[slug]", query: { slug: "post-1" } }}>
				Post 1 (alternative)
			</Link>
		</>
	);
}

useRouter Hook (Client)

"use client";

import { useRouter } from "next/navigation";

export function NavigateButton() {
	const router = useRouter();

	return <button onClick={() => router.push("/dashboard")}>Dashboard</button>;
}

Router Methods:

  • router.push(href) - Navigate to route
  • router.replace(href) - Replace current history
  • router.refresh() - Refresh current route
  • router.back() - Navigate back
  • router.forward() - Navigate forward
  • router.prefetch(href) - Prefetch route

Programmatic Navigation (Server)

import { redirect } from "next/navigation";

export default async function Page() {
	const session = await getSession();

	if (!session) {
		redirect("/login");
	}

	return <div>Protected content</div>;
}

Metadata & SEO

Static Metadata

// app/page.tsx
import { 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"],
	},
	twitter: {
		card: "summary_large_image",
		title: "My Page",
		description: "Page description",
		images: ["/twitter-image.jpg"],
	},
};

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

Dynamic Metadata

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

	return {
		title: post.title,
		description: post.excerpt,
		openGraph: {
			title: post.title,
			description: post.excerpt,
			images: [post.coverImage],
		},
	};
}

Metadata Files

  • favicon.ico, icon.png, apple-icon.png - Favicons
  • opengraph-image.png, twitter-image.png - Social images
  • robots.txt - Robots file
  • sitemap.xml - Sitemap

Image Optimization

Image Component

import Image from "next/image";

export default function Page() {
	return (
		<>
			{/* Local image */}
			<Image src="/profile.png" alt="Profile" width={500} height={500} />

			{/* Remote image */}
			<Image
				src="https://example.com/image.jpg"
				alt="Remote"
				width={500}
				height={500}
			/>

			{/* Responsive fill */}
			<div style={{ position: "relative", width: "100%", height: "400px" }}>
				<Image src="/hero.jpg" alt="Hero" fill style={{ objectFit: "cover" }} />
			</div>

			{/* Priority loading */}
			<Image src="/hero.jpg" alt="Hero" width={1200} height={600} priority />
		</>
	);
}

Image Props:

  • src - Image path (local or URL)
  • alt - Alt text (required)
  • width, height - Dimensions (required unless fill)
  • fill - Fill parent container
  • sizes - Responsive sizes
  • quality - 1-100 (default 75)
  • priority - Preload image
  • placeholder - 'blur-sm' | 'empty'
  • blurDataURL - Data URL for blur

Remote Image Configuration

// next.config.js
module.exports = {
	images: {
		remotePatterns: [
			{
				protocol: "https",
				hostname: "example.com",
				pathname: "/images/**",
			},
		],
	},
};

Font Optimization

Google Fonts

// app/layout.tsx
import { Inter, Roboto_Mono } from "next/font/google";

const inter = Inter({
	subsets: ["latin"],
	display: "swap",
});

const robotoMono = Roboto_Mono({
	subsets: ["latin"],
	display: "swap",
	variable: "--font-roboto-mono",
});

export default function RootLayout({ children }) {
	return (
		<html lang="en" className={`${inter.className} ${robotoMono.variable}`}>
			<body>{children}</body>
		</html>
	);
}

Local Fonts

import localFont from "next/font/local";

const myFont = localFont({
	src: "./fonts/my-font.woff2",
	display: "swap",
	variable: "--font-my-font",
});

Loading States

Loading File

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

Streaming with Suspense

// app/page.tsx
import { Suspense } from "react";

async function Posts() {
	const posts = await getPosts();
	return (
		<ul>
			{posts.map((p) => (
				<li key={p.id}>{p.title}</li>
			))}
		</ul>
	);
}

export default function Page() {
	return (
		<div>
			<h1>My Posts</h1>
			<Suspense fallback={<div>Loading posts...</div>}>
				<Posts />
			</Suspense>
		</div>
	);
}

Error Handling

Error File

// app/error.tsx
"use client";

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

Global Error

// app/global-error.tsx
"use client";

export default function GlobalError({
	error,
	reset,
}: {
	error: Error & { digest?: string };
	reset: () => void;
}) {
	return (
		<html>
			<body>
				<h2>Something went wrong!</h2>
				<button onClick={() => reset()}>Try again</button>
			</body>
		</html>
	);
}

Not Found

// app/not-found.tsx
export default function NotFound() {
	return (
		<div>
			<h2>404 - Not Found</h2>
			<p>Could not find requested resource</p>
		</div>
	);
}

// Trigger programmatically
import { notFound } from "next/navigation";

export default async function Page({ params }) {
	const post = await getPost(params.id);

	if (!post) {
		notFound();
	}

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

Middleware

// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(request: NextRequest) {
	// Authentication check
	const token = request.cookies.get("token");

	if (!token) {
		return NextResponse.redirect(new URL("/login", request.url));
	}

	// Add custom header
	const response = NextResponse.next();
	response.headers.set("x-custom-header", "value");

	return response;
}

export const config = {
	matcher: ["/dashboard/:path*", "/api/:path*"],
};

Environment Variables

# .env.local
DATABASE_URL=postgresql://...
NEXT_PUBLIC_API_URL=https://api.example.com

// Server-side only
const dbUrl = process.env.DATABASE_URL;

// Client and server (NEXT_PUBLIC_ prefix)
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

Configuration

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
	// React strict mode
	reactStrictMode: true,

	// Image domains
	images: {
		remotePatterns: [{ protocol: "https", hostname: "example.com" }],
	},

	// Redirects
	async redirects() {
		return [
			{
				source: "/old-page",
				destination: "/new-page",
				permanent: true,
			},
		];
	},

	// Rewrites
	async rewrites() {
		return [
			{
				source: "/api/:path*",
				destination: "https://api.example.com/:path*",
			},
		];
	},

	// Headers
	async headers() {
		return [
			{
				source: "/(.*)",
				headers: [{ key: "X-Frame-Options", value: "DENY" }],
			},
		];
	},

	// Environment variables
	env: {
		CUSTOM_KEY: "value",
	},
};

module.exports = nextConfig;

Best Practices

  1. Use Server Components: Default to Server Components, use Client Components only when needed
  2. Optimize Images: Always use next/image for automatic optimization
  3. Metadata: Set proper metadata for SEO
  4. Loading States: Provide loading UI with Suspense
  5. Error Handling: Implement error boundaries
  6. Route Handlers: Use for API endpoints instead of separate backend
  7. Caching: Leverage built-in caching strategies
  8. Layouts: Use nested layouts to share UI
  9. TypeScript: Enable TypeScript for type safety
  10. Performance: Use priority for above-fold images, lazy load below-fold

Common Patterns

Protected Routes

// app/dashboard/layout.tsx
import { redirect } from "next/navigation";
import { getSession } from "@/lib/auth";

export default async function DashboardLayout({ children }) {
	const session = await getSession();

	if (!session) {
		redirect("/login");
	}

	return <>{children}</>;
}

Data Mutations (Server Actions)

// app/actions.ts
"use server";

import { revalidatePath } from "next/cache";

export async function createPost(formData: FormData) {
	const title = formData.get("title");

	await db.post.create({ data: { title } });

	revalidatePath("/posts");
}

// app/posts/new/page.tsx
import { createPost } from "@/app/actions";

export default function NewPost() {
	return (
		<form action={createPost}>
			<input name="title" type="text" required />
			<button type="submit">Create</button>
		</form>
	);
}

Static Generation

// Generate static params for dynamic routes
export async function generateStaticParams() {
	const posts = await getPosts();

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

export default async function Post({ params }) {
	const post = await getPost(params.slug);
	return <article>{post.content}</article>;
}

Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

Self-Hosting

# Build
npm run build

# Start production server
npm start

Requirements:

  • Node.js 18.17 or later
  • output: 'standalone' in next.config.js (optional, reduces size)

Docker

FROM node:18-alpine AS base

FROM base AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static

EXPOSE 3000
CMD ["node", "server.js"]

Troubleshooting

Common Issues

  1. Hydration errors

    • Ensure server and client render same content
    • Check for browser-only code in Server Components
    • Verify no conditional rendering based on browser APIs

  2. Images not loading

    • Add remote domains to next.config.js
    • Check image paths (use leading / for public)
    • Verify width/height provided

  3. API route 404

    • Check file is named route.ts/js not index.ts
    • Verify export named GET/POST not default export
    • Ensure in app/api/ directory

  4. "use client" errors

    • Add 'use client' to components using hooks
    • Import Client Components in Server Components, not vice versa
    • Check event handlers have 'use client'

  5. Metadata not updating

    • Clear browser cache
    • Check metadata export is named correctly
    • Verify async generateMetadata returns Promise

Resources

Implementation Checklist

When building with Next.js:

  • Create project with create-next-app
  • Configure TypeScript and ESLint
  • Set up root layout with metadata
  • Implement routing structure
  • Add loading and error states
  • Configure image optimization
  • Set up font optimization
  • Implement data fetching patterns
  • Add API routes as needed
  • Configure environment variables
  • Set up middleware if needed
  • Optimize for production build
  • Test in production mode
  • Configure deployment platform
  • Set up monitoring and analytics

Repository

timelessco
timelessco
Author
timelessco/recollect/.claude/skills/nextjs
31
Stars
6
Forks
Updated1w ago
Added1w ago

Actions

View on GitHubDownload ZIPReport Issue

Related Skills

skill-writer
pytorch/pytorch
95.4k
docstring
pytorch/pytorch
95.4k
at-dispatch-v2
pytorch/pytorch
95.4k
add-uint-support
pytorch/pytorch
95.4k
skill-creator
openai/codex
54.7k