Next.js App Router Cookie Management

2.1.1 · active · verified Wed Apr 22

This library provides comprehensive cookie management for Next.js 13+ applications, specifically designed for the App Router. It offers solutions for both client-side components (SSR-capable) and server-only components. The current stable version is 2.1.1. While a specific release cadence isn't stated, the package appears actively maintained, indicated by recent updates and explicit migration instructions from v1. Key differentiators include its ability to support client components rendered on the server (SSR) with a special dehydration mechanism for cookie updates, a capability not natively offered by Next.js for server components. Its client-side interface is based on the popular `js-cookie` package, providing a familiar API. It addresses the challenge of handling cookies consistently across the varied rendering environments of Next.js's App Directory.

Common errors

```
TypeError: cookies.get is not a function
```
cause The `getCookies()` function in a Server Component was called without `await`, causing `cookies` to be a Promise object instead of the resolved cookie interface.

fix Change `const cookies = getCookies();` to `const cookies = await getCookies();`.
```
Error: useCookies() must be used within a Client Component.
```
cause Attempting to call the `useCookies` hook inside a Server Component (a file without the `'use client'` directive at the top).

fix Add `'use client';` at the very top of the file where `useCookies` is called, or refactor the cookie logic into a designated Client Component.
```
ReferenceError: CookiesProvider is not defined
```
cause The `CookiesProvider` component was used without being correctly imported or with an incorrect import path.

fix Ensure `import { CookiesProvider } from 'next-client-cookies/server';` is present in the file where `CookiesProvider` is used, typically `app/layout.tsx`.

Warnings

gotcha Placing `CookiesProvider` in `app/layout.tsx` will cause the entire application to opt out of static generation. Consider using it only on specific pages or nested layouts that require dynamic cookie access to maintain static generation for other parts of your app.
Fix: Apply `CookiesProvider` on a per-page or per-layout basis where cookie functionality is strictly required, instead of the root `app/layout.tsx`.
gotcha Next.js Server Components inherently do not support directly updating cookies outside of Actions or Route Handlers. While `next-client-cookies` offers a dehydration mechanism for client components rendered via SSR to update cookies, server-only components remain restricted to Next.js's native methods for server-side cookie modification.
Fix: For cookie updates in server-only components, utilize Next.js Server Actions or Route Handlers. If client-side interaction and SSR updates are needed, ensure the component is a Client Component (`'use client'`).
breaking When migrating from v1, the `getCookies` function is now asynchronous and must be `await`ed.
Fix: Update calls from `const cookies = getCookies();` to `const cookies = await getCookies();` in your server components.

Install

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

Imports

CookiesProvider
wrong:
```
import { CookiesProvider } from 'next-client-cookies';
```
correct:
```
import { CookiesProvider } from 'next-client-cookies/server';
```
This provider enables cookie functionality across your application and should be imported from the `/server` entry point.
useCookies
wrong:
```
const { useCookies } = require('next-client-cookies');
```
correct:
```
import { useCookies } from 'next-client-cookies';
```
This hook is designed for client components (`'use client'`) and enables read/write access to cookies on both client and server (via SSR).
getCookies
wrong:
```
const getCookies = require('next-client-cookies/server').getCookies;
```
correct:
```
import { getCookies } from 'next-client-cookies/server';
```
This function is for server-only components and must be `await`ed as it returns a Promise. Import from the `/server` entry point.

Quickstart

Demonstrates setting up CookiesProvider in `app/layout.tsx` and using the `useCookies` hook in a client component to read, set, and delete cookies.

'use client';

import { useCookies } from 'next-client-cookies';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <CookiesProvider>{children}</CookiesProvider>
      </body>
    </html>
  );
}

// In a client component (e.g., app/my-component.tsx)
// Make sure your component file starts with 'use client';
const MyCookieComponent = () => {
  const cookies = useCookies();

  return (
    <div>
      <p>My cookie value: {cookies.get('my-cookie') ?? 'Not set'}</p>

      <button onClick={() => cookies.set('my-cookie', 'my-value', { expires: 7 })}> 
        Set 'my-cookie'
      </button>
      {' | '}
      <button onClick={() => cookies.remove('my-cookie')}>Delete 'my-cookie'</button>
    </div>
  );
};

view raw JSON →