migrating-async-request-apis

Migrate Next.js 15 request APIs to async in Next.js 16.

Updated Nov 21, 2025

Search Tags:#migration #async #nextjs #params #cookies #searchParams

Ready to run

npx skills add https://github.com/djankies/claude-configs --skill migrating-async-request-apis

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: migrating-async-request-apis
Source: https://github.com/djankies/claude-configs/tree/main/nextjs-16/skills/migrating-async-request-apis
Command: npx skills add https://github.com/djankies/claude-configs --skill migrating-async-request-apis

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Next.js 16 changes request APIs to async (params, searchParams, cookies, headers, draftMode). This Skill guides migrations to await these APIs and adapt types accordingly.

Core Features & Use Cases

Phase-based migration guidance for route params, searchParams, and request APIs.
Concrete code patterns and edge cases for server components and route handlers.
Examples showing how to refactor to async parameters and awaited API calls.

Quick Start

Update function signatures to Promise-wrapped params/searchParams, await cookies()/headers(), and refactor component code accordingly.

Frequently Asked Questions about migrating-async-request-apis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I migrate Next.js request APIs to async in Next.js 16?▼

Migrate Next.js request APIs to async by updating params, searchParams, cookies(), headers(), and draftMode() to be awaited in your server components and route handlers. Next.js 16 changed these APIs to return Promises, requiring you to await them and update TypeScript types accordingly to reflect Promise-based returns.

Why am I getting Promise-related type errors after upgrading to Next.js 16?▼

Type errors occur because Next.js 16 made request APIs async. Your code is likely treating params, searchParams, cookies(), headers(), and draftMode() as synchronous values when they now return Promises. Add await keywords and update type annotations to Promise wrappers to resolve these errors.

Do I need to await params and searchParams in Next.js 16 layouts and pages?▼

Yes. In Next.js 16, params and searchParams are Promise-based and must be awaited in pages, layouts, and route handlers. This applies whether you're accessing route parameters or query strings; update your function signatures and component code to handle async values.

How do I handle cookies() and headers() as async APIs in route handlers?▼

In route handlers, call cookies() and headers() but await them since they now return Promises in Next.js 16. Update your code to use await before accessing their methods, and refactor any synchronous patterns to work with async/await or Promise-based flows.

What changes are needed for draftMode() in Next.js 16?▼

draftMode() is now async in Next.js 16. Await the draftMode() call before accessing its properties, and update your TypeScript types to reflect that it returns a Promise, particularly in server components and middleware.

What's the best approach to refactor multiple async request APIs at once during migration?▼

Phase the migration by updating one API type at a time—start with params, then searchParams, then cookies(), headers(), and draftMode(). This staged approach reduces the scope of type changes and testing, making it easier to identify issues and ensures each layer of your app adapts systematically.