Registry / web-framework / next-client-cookies

next-client-cookies

library2.1.1jsnpmunverified

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.

web-framework http-networking serialization

npm install next-client-cookies

github ↗package ↗

INSTALL

IMPORT

SIG · NEXT-CLIENT-COOKIE

next-client-cookies

web-frameworkjavascriptv2.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CookiesProvider

✓ import { CookiesProvider } from 'next-client-cookies/server';

✗ import { CookiesProvider } from 'next-client-cookies';

This provider enables cookie functionality across your application and should be imported from the `/server` entry point.

useCookies

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

✗ const { useCookies } = require('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

✓ import { getCookies } from 'next-client-cookies/server';

✗ const getCookies = require('next-client-cookies/server').getCookies;

This function is for server-only components and must be `await`ed as it returns a Promise. Import from the `/server` entry point.

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> ); };

Debug

Known issues

gotchaPlacing `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`.

affects: >=2.0.0

gotchaNext.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'`).

affects: >=2.0.0

breakingWhen 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.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: cookies.get is not a function

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.

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

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`.

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

nextrequiredRequired for Next.js application context and its App Router features.

reactrequiredRequired for React component usage and hooks within Next.js applications.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/moshest/next-client-cookies ↗

packagehttps://www.npmjs.com/package/next-client-cookies ↗