nextjs-advanced-routing

仓库: wsimmonds/claude-nextjs-skills
安装量: 118
排名: #7226

安装

npx skills add https://github.com/wsimmonds/claude-nextjs-skills --skill nextjs-advanced-routing

Next.js Advanced Routing Overview

Provide comprehensive guidance for advanced Next.js App Router features including Route Handlers (API routes), Parallel Routes, Intercepting Routes, Server Actions, error handling, draft mode, and streaming with Suspense.

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) { ... } 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) => { ... } const handleChange = (e: React.ChangeEvent) => { ... }

// Server actions async function myAction(formData: FormData) { ... }

When to Use This Skill

Use this skill when:

Creating API endpoints with Route Handlers Implementing parallel or intercepting routes Building forms with Server Actions Setting cookies or handling mutations Creating error boundaries Implementing draft mode for CMS previews Setting up streaming and Suspense boundaries Building complex routing patterns (modals, drawers) ⚠️ CRITICAL: Server Action File Naming and Location

When work requirements mention a specific filename, follow that instruction exactly. If no name is given, pick the option that best matches the project conventions—app/actions.ts is a safe default for collections of actions, while app/action.ts works for a single form handler.

Choosing between action.ts and actions.ts Match existing patterns: Check whether the project already has an actions file and extend it if appropriate. Single vs multiple exports: Prefer action.ts for a single action, and actions.ts for a group of related actions. Explicit requirement: If stakeholders call out a specific name, do not change it.

Location guidelines

Server actions belong under the app/ directory so they can participate in the App Router tree. Keep the file alongside the UI that invokes it unless shared across multiple routes. Avoid placing actions in lib/ or utils/ unless they are triggered from multiple distant routes and remain server-only utilities.

Example placement

app/ ├── actions.ts ← Shared actions that support multiple routes └── dashboard/ └── action.ts ← Route-specific action colocated with a single page

Example: Creating action.ts // app/action.ts (single-action example) 'use server';

export async function submitForm(formData: FormData) { const name = formData.get('name') as string; // Process the form console.log('Submitted:', name); }

Example: Creating actions.ts // app/actions.ts (multiple related actions) 'use server';

export async function createPost(formData: FormData) { // ... }

export async function deletePost(id: string) { // ... }

Remember: When a project requirement spells out an exact filename, mirror it precisely.

⚠️ CRITICAL: Server Actions Return Types - Form Actions MUST Return Void

This is a TypeScript requirement, not optional. Even if you see code that returns data from form actions, that code is WRONG.

When using form action attribute:

The function MUST have no return statement (implicitly returns void) TypeScript will REJECT any return value, even return undefined or return null IMPORTANT: If you see example code in the codebase that returns data from a form action, ignore it - it's an anti-pattern. Fix it by removing the return statement.

❌ WRONG (causes build error):

export async function saveForm(formData: FormData) { 'use server';

const name = formData.get('name') as string; if (!name) throw new Error('Name required');

await db.save(name); return { success: true }; // ❌ BUILD ERROR: Type mismatch }

// In component:

{/* ❌ Expects void function */}

✅ CORRECT - Option 1 (Simple form action, no response):

export async function saveForm(formData: FormData) { 'use server';

const name = formData.get('name') as string;

// Validate - throw errors instead of returning them if (!name) throw new Error('Name required');

await db.save(name); revalidatePath('/'); // Trigger UI update // No return statement - returns void implicitly }

// In component:

✅ CORRECT - Option 2 (With useActionState for feedback):

export async function saveForm(prevState: any, formData: FormData) { 'use server';

const name = formData.get('name') as string; if (!name) return { error: 'Name required' };

await db.save(name); return { success: true, message: 'Saved!' }; // ✅ OK with useActionState }

// In component: 'use client'; const [state, action] = useActionState(saveForm, null);

return (

{state?.error &&

{state.error}

} {state?.success &&

{state.message}

}

);

The key rule:

expects void. If you need to return data, use useActionState.

Route Handlers (API Routes) Basic Route Handler

Route Handlers replace API Routes from the Pages Router. Create them in route.ts or route.js files.

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

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

return Response.json({ message: 'Data received', data: body }); }

Supported HTTP Methods // app/api/items/route.ts export async function GET(request: Request) { } export async function POST(request: Request) { } export async function PUT(request: Request) { } export async function PATCH(request: Request) { } export async function DELETE(request: Request) { } export async function HEAD(request: Request) { } export async function OPTIONS(request: Request) { }

Dynamic Route Handlers // app/api/posts/[id]/route.ts export async function GET( request: Request, { params }: { params: { id: string } } ) { const id = params.id; const post = await db.posts.findUnique({ where: { id } });

return Response.json(post); }

export async function DELETE( request: Request, { params }: { params: { id: string } } ) { await db.posts.delete({ where: { id: params.id } });

return Response.json({ success: true }); }

Request Headers and Cookies // app/api/profile/route.ts import { cookies, headers } from 'next/headers';

export async function GET(request: Request) { // Access headers const headersList = await headers(); const authorization = headersList.get('authorization');

// Access cookies const cookieStore = await cookies(); const sessionToken = cookieStore.get('session-token');

if (!sessionToken) { return Response.json({ error: 'Unauthorized' }, { status: 401 }); }

const user = await fetchUser(sessionToken.value);

return Response.json(user); }

Setting Cookies in Route Handlers // app/api/login/route.ts import { cookies } from 'next/headers';

export async function POST(request: Request) { const { email, password } = await request.json();

const token = await authenticate(email, password);

if (!token) { return Response.json({ error: 'Invalid credentials' }, { status: 401 }); }

// Set cookie const cookieStore = await cookies(); cookieStore.set('session-token', token, { httpOnly: true, secure: process.env.NODE_ENV === 'production', maxAge: 60 * 60 * 24 * 7, // 1 week path: '/', });

return Response.json({ success: true }); }

CORS Configuration // app/api/public/route.ts export async function GET(request: Request) { const data = await fetchData();

return Response.json(data, { headers: { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization', }, }); }

export async function OPTIONS(request: Request) { return new Response(null, { status: 204, headers: { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization', }, }); }

Streaming Responses // app/api/stream/route.ts export async function GET() { const encoder = new TextEncoder();

const stream = new ReadableStream({ async start(controller) { for (let i = 0; i < 10; i++) { controller.enqueue(encoder.encode(data: ${i}\n\n)); await new Promise(resolve => setTimeout(resolve, 1000)); } controller.close(); }, });

return new Response(stream, { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', }, }); }

Server Actions

Server Actions enable server-side mutations without creating API endpoints.

Basic Server Action (Without Return) // app/actions.ts 'use server';

import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) { const title = formData.get('title') as string; const content = formData.get('content') as string;

const post = await db.posts.create({ data: { title, content }, });

revalidatePath('/posts'); // No return statement - Server Actions with forms should return void }

Note: See "Using Server Actions in Forms" section below for patterns that return data vs. those that don't.

⚠️ CRITICAL: Server Actions File Organization

File Naming Precision:

When stakeholders specify a filename (e.g., “create a server action in a file called action.ts”), mirror it exactly. Common filenames: action.ts (singular) or actions.ts (plural)—choose the one that matches the brief or existing code. Place the file in the appropriate directory: typically app/action.ts or app/actions.ts.

Two Patterns for 'use server' Directive:

Pattern 1: File-level (recommended for multiple actions):

// app/actions.ts 'use server'; // At the top - ALL exports are server actions

export async function createPost(formData: FormData) { ... } export async function updatePost(formData: FormData) { ... } export async function deletePost(postId: string) { ... }

Pattern 2: Function-level (for single action or mixed file):

// app/action.ts or any file export async function createPost(formData: FormData) { 'use server'; // Inside the function - ONLY this function is a server action

const title = formData.get('title') as string; await db.posts.create({ data: { title } }); }

Client Component Calling Server Action:

When a client component needs to call a server action (e.g., onClick, form submission):

Create the server action in a SEPARATE file with 'use server' directive Import and use it in the client component

✅ CORRECT Pattern:

// app/actions.ts - Server Actions file 'use server';

import { cookies } from 'next/headers';

export async function updateUserPreference(key: string, value: string) { const cookieStore = await cookies(); cookieStore.set(key, value);

// Or perform other server-side operations await db.userSettings.update({ [key]: value }); }

// app/InteractiveButton.tsx - Client Component 'use client';

import { updateUserPreference } from './actions';

export default function InteractiveButton() { const handleClick = () => { updateUserPreference('theme', 'dark'); };

return ( ); }

❌ WRONG - Mixing 'use server' and 'use client' in same file:

// app/CookieButton.tsx 'use client'; // This file is a client component

export async function setCookie() { 'use server'; // ERROR! Can't have server actions in client component file // ... }

Using Server Actions in Forms - Two Patterns Pattern 1: Simple Form Action (Returns void / Throws Errors)

CRITICAL: When using form action attribute directly, the Server Action MUST return void (nothing). Do NOT return { success: true } or any object.

VALIDATION RULE: Check all inputs and throw errors if validation fails. Do NOT return error objects.

⚠️ IMPORTANT: Even if you see example code in the codebase that returns { success: true } from a form action, do NOT copy that pattern. That code is an anti-pattern. Always:

Check/validate inputs Throw errors if validation fails (don't return error objects) Process the request Don't return anything (return void)

Correct pattern for form actions:

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

export async function createPost(formData: FormData) { const title = formData.get('title') as string; const content = formData.get('content') as string;

// Validate if (!title || !content) { throw new Error('Title and content are required'); }

// Save to database await db.posts.create({ data: { title, content } });

// Revalidate or redirect - no return needed revalidatePath('/posts'); }

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

export default function NewPost() { return (