Official Introduction

Ryan Carson's Experience

Installing Ralph

Manual Copy to Project

# Run from project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

# Copy the prompt template for your AI tool:
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # for Amp
# or
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md    # for Claude Code

chmod +x scripts/ralph/ralph.sh

Installing via Agent Skills

Manual Copy

# Amp
cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/

# Claude Code
cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/

Via Claude Code Plugin Marketplace

/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

After installation you'll have two skills:

• /prd — Generate a Product Requirements Document (PRD)
• /ralph — Convert PRD to prd.json format

Configuring Amp Auto Handoff

Edit ~/.config/amp/settings.json:

{
  "amp.experimental.autoHandoff": { "context": 90 }
}

This enables auto-handoff on context overflow, allowing Ralph to handle large user stories that exceed a single context window capacity.

Official Workflow

Creating a PRD

Use the PRD skill to generate a detailed requirements document:

Load the prd skill and create a PRD for [your feature description]

Answer the AI's clarifying questions. This command saves the output to tasks/prd-[feature-name].md.

Converting PRD to Ralph Format

Use the Ralph tool to convert the Markdown PRD into JSON format:

Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

This generates a prd.json file containing user stories structured for autonomous execution.

Running Ralph

# Using Amp (default)
./scripts/ralph/ralph.sh [max_iterations]

# Using Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

The default iteration count is 10. Use --tool amp or --tool claude to select the AI coding tool.

Ralph's execution flow:

1. Create a feature branch based on the branch name specified in the PRD
2. Pick the highest priority user story that is not yet completed (passes: false)
3. Implement the user story
4. Run quality checks (type checking, tests)
5. Commit if checks pass
6. Update prd.json, marking the story as completed (passes: true)
7. Append lessons learned to progress.txt
8. Repeat until all stories pass or maximum iterations are reached

Core Files

Core Concepts

Each Iteration = Fresh Context

Each iteration launches a brand new, context-clean AI instance (Amp or Claude Code). The only persisted state between iterations includes:

• Git history (commits from previous iterations)
• progress.txt (lessons learned and context information)
• prd.json (which user stories are completed)

Small Task Principle

Every requirement item in the PRD should be small enough to complete within a single context window. If tasks are too large, the LLM will exhaust its context before completion, resulting in poor quality code.

Appropriately sized user stories:

• Add a database field and migration script
• Add a new UI component to an existing page
• Add new logic and update a server action
• Add a filter dropdown to a list

Too large (needs splitting):

• "Build a complete dashboard"
• "Add authentication functionality"
• "Refactor the entire API"

AGENTS.md Updates Are Crucial

After each iteration, Ralph appends lessons learned to the corresponding AGENTS.md file. This is crucial — AI coding tools automatically read these files, and subsequent iterations as well as future developers benefit from the summarized development patterns, gotchas, and code conventions.

What to include in AGENTS.md:

• Development patterns: e.g., "This codebase uses X to implement Y"
• Gotchas: e.g., "When modifying W, always update Z"
• Useful context: e.g., "Settings panel is located in component X"

Feedback Loop

Ralph only works correctly when a feedback loop exists:

• Type checking catches type errors
• Tests verify functional behavior
• CI must remain passing (broken code accumulates problems across iterations)

Browser Verification for Frontend Stories

Frontend user story acceptance criteria must include "Verify in the browser using the dev-browser tool". Ralph will access the corresponding page via browser dev tools, interact with the UI, and confirm the modifications work correctly.

Stop Condition

When all user stories have passes set to true, Ralph outputs <promise>COMPLETE</promise> and exits the loop.

Debugging

Check current run status:

# See which stories are completed
cat prd.json | jq '.userStories[] | {id, title, passes}'

# View experience logs from previous iterations
cat progress.txt

# View Git commit history
git log --oneline -10

Archiving

When starting a new feature (using a different branch name), Ralph automatically archives previous run records. Archives are saved to archive/YYYY-MM-DD-feature-name/.

Installation

# Claude Official Plugin Marketplace
/plugin install superpowers@claude-plugins-official

# Superpowers Plugin Marketplace
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Cursor
/add-plugin superpowers

# Codex
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

# OpenCode
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

# Gemini
gemini extensions install https://github.com/obra/superpowers
gemini extensions update superpowers

Workflow

Superpowers defines a complete software engineering workflow, breaking down the AI coding process into multiple stages, each with clear skills/commands, triggers, and deliverables.

Requirements Clarification

• Skill/Command: Brainstorming (/brainstorming or /superpowers:brainstorming)
• Trigger: User proposes a new feature or requirement (e.g., "Add user login functionality")
• Input/Output: Input is user's natural language requirements; output is clarifying Q&A and preliminary design discussion. Deliverable: Requirements specification document (text format) listing key requirements.
• Notes: The skill uses Socratic questioning to clarify boundaries and requirement details (e.g., supported login methods, error handling logic). Must obtain user confirmation before proceeding. If user answers are ambiguous or incomplete, continue asking. If answers are inconsistent, re-verify requirements.

Design & Architecture

• Skill: Can be seen as a continuation of Brainstorming, or implicit in Plans; includes design review.
• Trigger: Automatically proceeds after Brainstorming requirements are confirmed.
• Input/Output: Input is the clarified requirements; output is system architecture or module division suggestions. Deliverable: System architecture sketch or component list.
• Notes: Design should follow best practices, be clear and concise. If the design is insufficient, return to the Brainstorming phase to supplement requirements or rethink. Use Brainstorming output to verify design soundness.

Plan Breakdown

• Skill/Command: Writing Plans (/writing-plans or /superpowers:writing-plans)
• Trigger: After design plan is confirmed, input requirements to begin task breakdown.
• Input/Output: Input is requirements specification or design document; output is detailed implementation steps. Deliverable: Implementation plan document listing multiple small tasks (each including goal, file paths, example code, verification steps).
• Notes: Each task should be completable within 2–5 minutes. Follow DRY/YAGNI principles, implement only what's necessary. If task granularity is too large or too small, adjust accordingly. Continuously confirm the plan with the user during execution.

Creating a Git Worktree

• Skill/Command: Using Git Worktrees (implicit, no explicit command)
• Trigger: Automatically created when ready to start coding after implementation plan is generated.
• Input/Output: Executes Git commands in the local project. Deliverable: New development branch and corresponding working directory (e.g., git worktree add -b <feature> ...).
• Notes: Isolated development environment prevents affecting the main branch. If serious issues arise, the worktree branch can be deleted while keeping the main branch clean. Clean up (git worktree remove) after completion to free resources.

Implementation & Coding

• Skill/Command: Execute Plans (/execute-plan or /superpowers:executing-plans), paired with Test-Driven Development.
• Trigger: Starts when the user agrees to the execution plan or after the planning phase is complete.
• Input/Output: Input is the task list; output is code and tests. AI implements tasks sequentially per plan, opening new sessions or sub-agents for each task.
• Deliverable: Feature code files, corresponding test code, task execution logs.
• Notes: Enforces TDD flow: before implementing each feature, first write a failing test (red), then write minimal code to pass it (green), and finally refactor. AI does not write production code without first writing a failing test. If many failures or logic confusion occurs, pause the current task for debugging; commit promptly after each task completes.

Test-Driven Development (TDD)

• Skill/Command: Test-Driven Development (/superpowers:test-driven-development)
• Trigger: Automatically triggered at the start of each coding task.
• Input/Output: Input is task description; output is test cases and implementation code. Deliverable: Unit test files and implementation files.
• Notes: Follows the "red-green-refactor" cycle. If test cases are written incorrectly and fail to fail, they should be rewritten. Tasks must not be marked complete before tests pass. AI automatically rolls back incorrect test-first attempts.

Systematic Debugging

• Skill/Command: Systematic Debugging (/superpowers:systematic-debugging)
• Trigger: Actively triggered when encountering failing tests, runtime errors, or functional anomalies during coding.
• Input/Output: Input is error description and current code context; output is debugging analysis report. Deliverable: Four-stage debugging record (root cause analysis, pattern recognition, hypothesis testing, fix recommendations).
• Notes: Must follow the root cause first principle: analyze the problem's essence before applying fixes. If still unresolved after three attempts, consider whether the issue lies in requirements or design, and if necessary, return to previous stages for review or seek human help. Record all debugging hypotheses and conclusions for future reference.

Code Review

• Skill/Command: Request Code Review (/request-code-review)
• Trigger: Triggered after all tasks on a feature branch are complete and all tests pass.
• Input/Output: Input is the current branch's code changes; output is a review report. Deliverable: Code review feedback (strengths, defects, improvement suggestions).
• Notes: Automated review checks against code style, security, performance, and other standards, producing a graded issue report. If critical issues are found, they must be fixed and the review re-run; general issues can be followed up after merge. When fixing, modify code as suggested and re-run tests and review.

Merge & Release

• Skill/Command: Finish Branch (merge, no explicit command)
• Trigger: Executed when all review issues are resolved and functionality is confirmed correct.
• Input/Output: Input is the reviewed branch; output is the merge operation. Deliverable: Merged main branch code.
• Notes: Default behavior: verify all tests pass before merging. Provides merge/PR, keep, or delete options. Clean up Git worktrees (git worktree remove) after merge to free space. Merge marks official completion; deployment or release can happen at this stage.

Retrospective & Summary

• Skill: No specific Superpowers skill.
• Trigger: Optional, after merge is complete.
• Deliverable: Project summary document (project experience, list of open issues).
• Notes: Recommended for teams or AI to summarize project outcomes and issues as reference for future process improvement.

Case Study

User: /brainstorming I want to add user login functionality to my website
Claude (Brainstorming skill triggered):
  Let me clarify a few questions before we begin:
  1. Login method: email+password, phone+verification code, or third-party login?
  2. Do you need a "Remember Me" feature?
  3. How should login failures be communicated to the user?
  ...
User: We just need email+password login, simple error messages will do.
Claude:
  Understood. Requirements analysis results: User login feature needs email and password input, encrypted password storage; display error messages on the frontend on login failure; return user info on successful login. Please confirm to proceed (/writing-plans).
User: Continue
Claude: /writing-plans
Claude (Writing Plans skill triggered):
  Based on the requirements, I've generated an implementation plan for the "User Login" feature:
  - Task 1: Create a user table model in `src/models/user.js` (fields: email, passwordHash). **First write a failing test** verifying a newly registered user can log in.
  - Task 2: Implement login logic in `src/auth/login.js` (verify password and generate JWT). **First write a failing test** ensuring correct credentials allow login.
  - Task 3: Add a login form in the frontend `src/components/LoginForm.vue` (email/password). **First write a failing test** checking form submission calls the Login API.
  Please confirm the plan and start execution.
User: Confirmed
Claude:
  Plan generated, starting task execution... (running `/execute-plan`)
Claude:
  Creating isolated Git worktree... (`git worktree add -b feature/login .claude/branches/feature/login`)
  Starting sub-agent task 1: TDD cycle...
  First write test `test/user.test.js`: verify new user can login [Red]...
  Write implementation: `src/models/user.js` create model, add passwordHash field, compare hash on login [Green]...
  Running tests...All pass!
  Commit changes (`git add && git commit`).
  Starting task 2...
  Write test `test/auth.test.js`: verify login logic with registered user [Red]...
  Implement `src/auth/login.js`: find user and verify password hash, generate JWT [Green]...
  Tests pass!
  Starting task 3...
  Write test `test/loginForm.test.js`: simulate form submission and check Login API call [Red]...
  Implement `src/components/LoginForm.vue`: add form and connect to backend [Green]...
  Tests pass! All tasks complete.
Claude:
  All tests passed. Now running code review. (/request-code-review)
Claude (Request Code Review skill triggered):
  Reviewing tasks...
  * Task 1 module: Naming conventions are compliant, no issues.
  * Task 2 module: Found a potential issue — password hash is missing salt, recommend adding it.
  * Task 3 module: Frontend submission is missing error handling, recommend improving error messaging.
  Found 1 significant issue, please fix and re-review.
User: OK, I'll fix it
Claude:
  Issues fixed, all tests pass. Code review approved.
Claude:
  Preparing to merge branch (finish-branch)... Merge successful, feature branch closed.

Note: In the case above, the user sequentially executes /brainstorming, /writing-plans, confirms and runs /execute-plan to trigger coding. AI creates an isolated Git worktree and completes three tasks through TDD cycles. Output includes requirements specification, task list, test results, code snippets, and review report. /request-code-review triggers automatic review and reports issues, which are fixed before merging. All commands (e.g., /execute-plan, /request-code-review) can be used directly in the Claude Code environment.

Skills Overview

• spec-kit Official Repository
• SDD — Spec-Driven Development
• spec-kit Detailed Process

Quick Start

Installing spec-kit

# Install a specific stable version (recommended — replace vX.Y.Z with the latest tag)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# Or install the latest from the main branch (may include unreleased changes)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Upgrade spec-kit
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Initializing a Project

# Create a new project
specify init <PROJECT_NAME>

# Or initialize in an existing project
specify init . --ai claude

# Specify AI coding agent and use skills
specify init . --ai claude --ai-skills

# Or
specify init --here --ai claude

# Check installed tools
specify check

Setting Project Constitution

Launch the AI assistant in your project directory. Most agents expose spec-kit as /speckit.* slash commands; Codex CLI uses $speckit-* in skill mode.

Use the /speckit.constitution command to create project governance principles and development guidelines:

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

Creating Specifications

Use the /speckit.specify command to describe what you want to build. Focus on the "what" and "why", not the tech stack.

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

Creating a Technical Implementation Plan

Use the /speckit.plan command to provide tech stack and architectural choices:

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

Breaking Down Tasks

Use /speckit.tasks to generate an actionable task list based on the implementation plan:

/speckit.tasks

Executing Tasks

Use /speckit.implement to execute all tasks and build your feature according to the plan:

/speckit.implement

Slash Command Reference

Core Commands

Optional Commands

spec-kit Command Reference

# Basic project initialization
specify init my-project

# Specify AI assistant
specify init my-project --ai claude

# Initialize with Cursor support
specify init my-project --ai cursor-agent

# Initialize with Qoder support
specify init my-project --ai qodercli

# Initialize with Windsurf support
specify init my-project --ai windsurf

# Initialize with Kiro CLI support
specify init my-project --ai kiro-cli

# Initialize with Amp support
specify init my-project --ai amp

# Initialize with SHAI support
specify init my-project --ai shai

# Initialize with Mistral Vibe support
specify init my-project --ai vibe

# Initialize with IBM Bob support
specify init my-project --ai bob

# Initialize with Pi Coding Agent support
specify init my-project --ai pi

# Initialize with Codex CLI support
specify init my-project --ai codex --ai-skills

# Initialize with Antigravity support
specify init my-project --ai agy --ai-skills

# Initialize with Forge support
specify init my-project --ai forge

# Initialize with generic support for unsupported agents
specify init my-project --ai generic --ai-commands-dir .myagent/commands/

# Initialize with PowerShell script support (Windows/cross-platform)
specify init my-project --ai copilot --script ps

# Initialize in current directory
specify init . --ai copilot
# Or use the --here flag
specify init --here --ai copilot

# Force merge into current (non-empty) directory without confirmation
specify init . --force --ai copilot
# Or
specify init --here --force --ai copilot

# Skip Git initialization
specify init my-project --ai gemini --no-git

# Enable debug output
specify init my-project --ai claude --debug

# Use GitHub Token for API requests (suitable for enterprise environments)
specify init my-project --ai claude --github-token ghp_your_token_here

# By default, Claude Code installs skills in the project
specify init my-project --ai claude

# Initialize in current directory and use agent skills
specify init --here --ai gemini --ai-skills

# Use timestamp branch numbering (suitable for distributed teams)
specify init my-project --ai claude --branch-numbering timestamp

# Check system requirements
specify check

Extensions & Presets

.specify/templates/overrides/         # Local project overrides (highest priority), for one-time adjustments without creating a full preset
.specify/presets/templates/           # Custom extensions and core templates
.specify/extensions/templates/        # Enhance spec-kit capabilities
.specify/templates/                   # spec-kit's core built-in templates

Extensions

Use extensions when you need functionality beyond spec-kit's core. Extensions introduce new commands and templates — for example, adding domain-specific workflows not covered by built-in SDD commands, integrating external tools, or adding entirely new development phases. They extend spec-kit's capabilities.

For example, extensions can add Jira integration, post-implementation code review, V-Model test traceability, or project health diagnostics.

Community Extensions

specify extension search

# Install an extension
specify extension add <extension-name>

Presets

Use presets when you need to change how spec-kit works without adding new features. Presets override templates and commands from the core and installed extensions — for example, enforcing compliance-oriented spec formats, adopting domain-specific terminology, or applying organizational standards to plans and tasks. They customize the artifacts and instructions generated by spec-kit and its extensions.

For instance, presets can restructure spec templates to require regulatory traceability, adapt workflows to fit adopted methodologies (such as Agile, Kanban, Waterfall, Jobs-to-be-Done, or Domain-Driven Design), add security review gates to plans, enforce test-first task ordering, or localize the entire workflow into different languages. The pirate-speak demo demonstrates the depth of customization. Multiple presets can be stacked in priority order.

• Community Presets
• Preset Documentation

specify preset search

# Install a preset
specify preset add <preset-name>

open-spec

Coming soon…

Next.js 15 brings powerful features that make building modern web applications easier than ever. This guide starts with the fundamentals and systematically walks through the complete App Router ecosystem — from the routing system and layout management to data fetching, rendering strategies, and error handling — helping you build a comprehensive knowledge framework.

App Router Basics

The App Router is the foundation of modern Next.js applications. It uses file-system routing, where the directory structure maps directly to page paths. Here's a simple routing example:

// app/page.tsx
export default function HomePage() {
  return (
    <main>
      <h1>Welcome to Next.js 15</h1>
    </main>
  )
}

Files created inside the app directory are automatically mapped to corresponding routes:

Layout System

Layouts are a highlight of the Next.js App Router, making it incredibly easy to share UI across pages.

Root Layout

Every application must have a root layout (app/layout.tsx), which wraps all pages:

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

Nested Layouts

You can add layout.tsx at any route segment level, and layouts are automatically nested. Layouts preserve state during navigation and do not re-render:

// app/blog/layout.tsx
// Shared by all /blog/* pages
export default function BlogLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div>
      <Sidebar />
      <article>{children}</article>
    </div>
  )
}

Templates

Templates (template.tsx) are similar to layouts but re-render on every navigation, making them suitable for scenarios that require state reset (such as page view tracking):

// app/blog/template.tsx
export default function BlogTemplate({
  children,
}: {
  children: React.ReactNode
}) {
  return <div className="page-enter-animation">{children}</div>
}

Advanced Routing

Route Groups

Use (groupName) directory structure to organize routes without affecting the URL path. Useful for grouping routes by module or applying different layouts to different groups:

app/
  (marketing)/
    page.tsx          // /
    about/page.tsx    // /about
  (shop)/
    products/
      page.tsx        // /products
    cart/page.tsx     // /cart

Parallel Routes

Render multiple pages simultaneously within the same layout using named slots (@slotName), ideal for dashboards or multi-section pages:

// app/layout.tsx
export default function Layout({
  children,
  team,
  analytics,
}: {
  children: React.ReactNode
  team: React.ReactNode
  analytics: React.ReactNode
}) {
  return (
    <>
      {children}
      <div className="grid grid-cols-2">
        {team}
        {analytics}
      </div>
    </>
  )
}

Loading & Error Handling

Next.js 15 provides built-in loading and error boundaries for each route segment.

Loading UI

Add loading.tsx to display a skeleton screen or loading animation while the page is loading, providing instant feedback through streaming:

// app/blog/loading.tsx
export default function Loading() {
  return (
    <div className="space-y-4">
      <Skeleton className="h-8 w-3/4" />
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-2/3" />
    </div>
  )
}

Error Boundaries

error.tsx wraps route segments and catches rendering exceptions. It must be a client component:

// app/blog/error.tsx
'use client'

export default function ErrorPage({
  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>
  )
}

404 Page

Customize the Not Found page via not-found.tsx, or trigger it programmatically with notFound():

// app/not-found.tsx
export default function NotFound() {
  return (
    <div>
      <h1>404 - Page Not Found</h1>
      <Link href="https://charliefei.github.io/">Back to Home</Link>
    </div>
  )
}

Global Error

global-error.tsx wraps the entire application and is used only when a critical error occurs in the root layout (must include <html> and <body> tags):

// app/global-error.tsx
'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>A critical application error occurred</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

Key Features

• Server Components: Rendered on the server by default, reducing client-side JavaScript and improving initial load performance. They can directly access databases and file systems without exposing API endpoints.
• Streaming: Supports progressive HTML chunk transmission to the client, allowing users to see content faster without waiting for the entire page to generate. Works with loading.tsx for a smooth loading experience.
• Metadata API: Define page title, description, Open Graph metadata, and more in a type-safe way by exporting metadata objects or generateMetadata function, making SEO optimization easy.
• Server Actions: Define form submission and data mutation logic directly in server components without manually creating API routes, simplifying front-end/back-end interaction. Supports progressive enhancement (falls back to traditional form submission when JavaScript is unavailable).

Data Fetching

Next.js 15 offers flexible data fetching approaches. You can use async/await directly in server components:

// app/posts/page.tsx
async function getPosts() {
  const res = await fetch('https://api.example.com/posts')
  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>
  )
}

Thanks to server components, data fetching happens on the server side — no API credentials are exposed, and no additional data request logic needs to be loaded on the client.

fetch Caching Strategies

The built-in fetch supports fine-grained cache control:

// Static data request — default behavior, caches the result
const staticData = await fetch('https://...')

// Dynamic data request — re-fetches on every request
const dynamicData = await fetch('https://...', { cache: 'no-store' })

// Time-based incremental revalidation — re-fetches every 10 seconds
const revalidatedData = await fetch('https://...', {
  next: { revalidate: 10 },
})

Database Queries

Server components can query databases directly without writing API routes:

export default async function UserProfile({ params }: { params: { id: string } }) {
  const user = await db.users.findUnique({
    where: { id: params.id },
  })

  return <div>{user.name}</div>
}

Rendering Strategies

Next.js 15 offers multiple rendering modes that can be flexibly chosen based on page characteristics.

Static Rendering

The default rendering mode. Routes are rendered at build time, cached, and can be distributed via CDN. Ideal for content pages, blog posts, and other infrequently changing content.

export const dynamic = 'force-static'

Dynamic Rendering

Routes are rendered dynamically on each request. Suitable for personalized content and real-time data:

export const dynamic = 'force-dynamic'

Incremental Static Regeneration (ISR)

Combines the benefits of static and dynamic — serve statically, update on demand. Suitable for scenarios where data changes periodically but does not require real-time updates:

// Page-level ISR
export const revalidate = 3600 // Regenerate every hour

Route Segment Configuration

Each route segment can be finely controlled through exported configuration options:

export const dynamic = 'auto'           // Auto-select static/dynamic
export const dynamicParams = true        // Auto-handle ungenerated dynamic params
export const revalidate = false          // Revalidation interval (seconds)
export const fetchCache = 'auto'         // fetch cache strategy
export const runtime = 'nodejs'          // Runtime environment
export const preferredRegion = 'auto'    // Deployment region

Middleware

Middleware (middleware.ts) executes before a request completes, used for redirects, rewrites, authentication, i18n routing, and more:

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

export function middleware(request: NextRequest) {
  // Redirect user based on cookie
  if (!request.cookies.has('session')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}

// Configure matching paths
export const config = {
  matcher: ['/dashboard/:path*', '/admin/:path*'],
}

Summary

Next.js 15 provides a solid and elegant foundation for building high-performance web applications. This article covers the core concepts from routing system, layout management, and data fetching to rendering strategies and error handling. Key takeaways:

• File-system routing makes page organization intuitive at a glance
• Layouts and loading boundaries provide elegant UI composition and user experience
• Server components simplify data fetching and improve performance
• Multiple rendering strategies let you choose the optimal approach for each scenario
• Built-in error handling ensures application robustness

These are just some of Next.js's capabilities. Start with these fundamentals and gradually explore more advanced features in practice.