Next.js Cookies Management

6.1.1 · active · verified Sun Apr 19

cookies-next is a specialized library designed for managing HTTP cookies within Next.js applications, supporting operations on both the client and server sides, including Server Components and API routes. The current stable version is 6.1.1. It maintains a relatively active release cadence, frequently updating to support new Next.js versions and introduce features like React hooks for client-side state management, including 'reactive hooks' that trigger component re-renders when cookie values change. Key differentiators include its explicit support for Next.js's distinct client and server environments, offering separate import paths for optimized bundles, and providing both static and reactive hooks for flexible client-side usage, distinguishing it from general-purpose cookie libraries.

Common errors

```
Error: Cookies must be used within a server context or be provided manually.
```
cause Attempting to use server-side cookie functions (e.g., `getCookie` directly in a Server Component without passing the `cookies` object from `next/headers`).

fix Import `cookies` from `next/headers` and pass it as an option: `const myCookie = getCookie('mykey', { cookies: cookies() });`
```
TypeError: Cannot read properties of undefined (reading 'headers') during SSR
```
cause This error can occur if server-side cookie functions are called in a context where `req` and `res` objects (or `cookies` from `next/headers`) are not available or not properly passed, especially when using the universal `cookies-next` import.

fix Ensure that server-side cookie operations are performed within a `getServerSideProps`, API route, or Server Component where `req`/`res` or the `cookies` object from `next/headers` are accessible and passed to the functions as options.
```
Hydration failed because the initial UI does not match what was rendered on the server.
```
cause Cookies can differ between server-side render and client-side hydration, causing content mismatches if components render differently based on cookie values, especially if cookies are set after the initial server render.

fix Use client-side hooks within components marked with 'use client' and ensure any cookie-dependent rendering logic is robustly handled or deferred until the client-side. For SSR, ensure that server-set cookies are consistent or handle variations gracefully.

Warnings

breaking Version 5.0.0 introduced significant changes to support Next.js 15+, including new explicit client (`cookies-next/client`) and server (`cookies-next/server`) import paths. Applications on Next.js 15+ must update their import statements, or use the root import which attempts to auto-detect the environment.
Fix: For Next.js 15+, update imports to `from 'cookies-next/client'` for client components and `from 'cookies-next/server'` for server components/API routes. Alternatively, use `from 'cookies-next'` but be aware of potential bundle size implications for older Next.js versions.
breaking Prior to v6.0.0, the `useGetCookies` hook and similar client-side hooks were static and did not trigger component re-renders when cookie values changed externally. Version 6.0.0 changed this behavior, making hooks trigger re-renders to reflect updated cookie states.
Fix: Review components using client-side cookie hooks (`useGetCookies`, `useGetCookie`, etc.) after upgrading to v6.0.0. If you relied on the static behavior, you might experience unexpected re-renders. Consider using reactive hooks where explicit re-rendering is desired or adjust component logic.
gotcha When using `setCookie` or `deleteCookie` on the server-side with Next.js 13+ App Router, you must explicitly pass the `cookies` object obtained from `next/headers` to the options parameter to correctly manipulate the response headers.
Fix: Ensure you import `cookies` from `next/headers` and pass `{ cookies }` as an option to `setCookie` or `deleteCookie` when operating in Server Components or API routes (e.g., `setCookie('key', 'value', { cookies });`).
gotcha Client-side reactive cookie hooks (e.g., `useCookiesNext` when used with the provider) require the `CookiesNextProvider` to be added higher up in your component tree to manage their internal React state and context correctly.
Fix: Wrap your application or relevant client components with `CookiesNextProvider` to enable the reactive functionality of hooks like `useCookiesNext` or those imported from `cookies-next/client`.

Install

npm install cookies-next npm
yarn add cookies-next yarn
pnpm add cookies-next pnpm

Imports

getCookie, setCookie
wrong:
```
const { getCookie, setCookie } = require('cookies-next')
```
correct:
```
import { getCookie, setCookie } from 'cookies-next'
```
For universal usage (auto-detects client/server). Modern Next.js apps use ESM; CommonJS `require` is generally incorrect for contemporary usage.
getCookie, setCookie (client-side)
wrong:
```
import { getCookie, setCookie } from 'cookies-next'
```
correct:
```
import { getCookie, setCookie } from 'cookies-next/client'
```
Explicitly imports client-side functions. Recommended for client components in Next.js 15+ to ensure tree-shaking and avoid server-side code bundles.
getCookie, setCookie (server-side)
wrong:
```
import { getCookie, setCookie } from 'cookies-next'
```
correct:
```
import { getCookie, setCookie } from 'cookies-next/server'
```
Explicitly imports server-side functions. Recommended for Server Components or API routes in Next.js 15+ for clarity and bundle optimization.
useCookiesNext
```
import { useCookiesNext } from 'cookies-next'
```
A client-side hook providing all cookie functions. Requires 'use client' directive for the component.

Quickstart

Demonstrates server-side cookie management within a Next.js App Router API route, including setting, getting, and deleting cookies. It shows how to integrate with Next.js's native `cookies` function for server contexts.

import { getCookie, setCookie, deleteCookie } from 'cookies-next/server';
import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';

// Example: API Route for server-side operations (Next.js App Router)
export async function GET(request: Request) {
  const serverCookies = cookies(); // Access Next.js headers cookies
  const myCookie = getCookie('my-server-cookie', { cookies: serverCookies });
  console.log('Server-side myCookie:', myCookie);

  if (!myCookie) {
    setCookie('my-server-cookie', 'server-value', { 
      cookies: serverCookies, 
      maxAge: 60 * 60 * 24, 
      path: '/',
      httpOnly: true
    });
    return NextResponse.json({ message: 'Cookie set!', value: 'server-value' });
  }
  
  return NextResponse.json({ message: 'Cookie already exists', value: myCookie });
}

// Example: Client Component usage (for demonstration, this would be in a '.tsx' file with 'use client')
// 'use client';
// import { useSetCookie, useGetCookie, useDeleteCookie } from 'cookies-next';
// import { useEffect } from 'react';

// function ClientCookieDemo() {
//   const setClientCookie = useSetCookie();
//   const getClientCookie = useGetCookie();
//   const deleteClientCookie = useDeleteCookie();

//   useEffect(() => {
//     setClientCookie('my-client-cookie', 'client-value', { maxAge: 3600 });
//     const val = getClientCookie('my-client-cookie');
//     console.log('Client-side my-client-cookie:', val);
//   }, [setClientCookie, getClientCookie]);

//   return (
//     <div>
//       <p>Client-side cookie operations demonstrated.</p>
//       <button onClick={() => deleteClientCookie('my-client-cookie')}>Delete Client Cookie</button>
//     </div>
//   );
// }
// export default ClientCookieDemo;

view raw JSON →