nextjs-advanced-routing_skill

Overview

This skill is a practical guide for advanced Next.js App Router patterns: Route Handlers (route.ts), Parallel and Intercepting Routes, Server Actions (action.ts / actions.ts), error boundaries, draft mode, and streaming with Suspense. It emphasizes critical conventions for server actions, form handling, cookie management, and TypeScript safety so your app builds and behaves correctly. Follow the rules here to avoid common runtime and TypeScript build errors.

How this skill works

The skill inspects and documents correct patterns for colocating server actions under app/, naming action files precisely, and using the 'use server' directive either file-level or function-level. It explains how to implement route handlers (route.ts), access headers and cookies, set cookies from server code, and stream responses. It also covers form usage: when a form uses action={serverAction} the action must return void and validation must throw errors rather than return objects.

When to use it

• Building API endpoints with Route Handlers (route.ts)
• Creating server-side mutations and form handlers with Server Actions
• Setting or reading cookies from server code called by client components
• Implementing parallel routes, intercepting routes, or modal/drawer routing patterns
• Setting up streaming responses and Suspense boundaries for progressive rendering
• Adding error boundaries or draft mode for CMS previews

Best practices

• Never use the any type — prefer precise typings for params, searchParams, and events
• Place server actions in app/ and name files exactly as project requirements specify (action.ts vs actions.ts)
• Use 'use server' at file-level for groups of actions or inside a function for a single action
• Form actions referenced by <form action={...}> must not return a value; throw errors for validation
• Keep server-only logic out of client components; import server actions from separate files
• Use revalidatePath or redirects to update UI after server-side mutations instead of returning data from form actions

Example use cases

• app/api/*/route.ts to implement REST endpoints and dynamic route handlers
• app/actions.ts to host create/update/delete mutations consumed by client components
• Colocated app/dashboard/action.ts for a single-form handler used only by that route
• Setting a session cookie in an authentication route handler and reading it in other route handlers
• Streaming server-sent data from app/api/stream/route.ts while rendering Suspense boundaries in the page