Proposal: Standardize server-side cookie API across middleware, server actions, and API routes

[mattiamalonni]

Goals

1. Provide a consistent API to read, write, and delete cookies across all server environments (middleware, server actions, API routes, route handlers).
2. Eliminate the need to branch logic or pass context to shared utilities when accessing cookies.
3. Ensure cookie changes made in middleware are reliably available later in the request lifecycle.

Non-Goals

1. Does not aim to change client-side cookie handling (document.cookie).
2. Does not propose any new cookie features — only alignment of existing capabilities.
3. Does not intend to change or unify request and response objects across runtimes.

Background

Next.js provides different APIs for cookie access depending on the execution environment:

• In middleware, cookies are read/written via NextRequest.cookies and NextResponse.cookies.
• In server actions, route handlers, and API routes, the standard is to use cookies() from next/headers.

This split introduces inconsistency and confusion for developers. Not only is the API surface different, but the behavior also diverges in subtle ways — especially when cookies are set in middleware and accessed downstream.

Example: Middleware sets a cookie, but server action can't read it

// middleware.ts
const response = NextResponse.next();
response.cookies.set('user-session', 'abc123');
return response;


// app/page.tsx (server component or action)
const cookieStore = await cookies()
const session = cookieStore.get('user-session'); // ❌ undefined or stale

The reason: cookies() reads from the original incoming request, which hasn’t been modified by the middleware. This breaks the mental model that setting a cookie early in the lifecycle should make it available later.

Additional challenges:
• Shared utilities (e.g. for auth/session handling) must branch logic to check context?.nextRequest?.cookies vs. cookies().
• Middleware often requires duplicating logic to ensure cookies are set and read correctly.
• The discrepancy leads to boilerplate, fragile code, and developer confusion.

A unified approach would allow developers to reason about cookies in a consistent way across all server contexts.

Proposal

Introduce a standard, context-aware cookie API that works consistently across middleware, server actions, route handlers, and API routes.

Make cookies() universally available

• Allow cookies() from next/headers to be used in middleware as well.
• Under the hood, it can detect the environment and use the appropriate cookie store (e.g., from NextRequest/NextResponse in middleware).
• It should support both reading from the original request and writing to the response where applicable.

Such a change would greatly reduce duplication, clarify expectations, and offer a smoother developer experience for common tasks like authentication, sessions, flash messages, and experimentation.

[SametDulger]

Hi @mattiamalonni,

Thanks for sharing this proposal. I fully agree that having a unified server-side cookie API across middleware, server actions, API routes, and route handlers would be a big improvement.

Currently, cookie handling differs between middleware (using NextRequest.cookies and NextResponse.cookies) and server actions or API routes (using cookies() from next/headers). This causes duplicated logic, extra branching, and confusion.

Your example clearly shows that cookies set in middleware are not accessible later in server actions, which breaks the expected behavior.

A standard, context-aware cookies() API that works the same way everywhere, detects the environment, and handles reading and writing properly would simplify development, reduce boilerplate, and make shared utilities like auth or sessions easier to implement.

I look forward to this proposal progressing. Let me know if I can help test or give feedback.