cookies-next

Standard hooks are stateless. For reactive behavior (where components update when cookies change), use CookiesNextProvider and reactive hooks.

By default, polling is disabled. You can enable it via pollingOptions to monitor document.cookie for changes made outside of cookies-next (e.g., by the server).

Setup Provider:

<CookiesNextProvider pollingOptions={{ enabled: true, intervalMs: 1000 }}>
  {children}
</CookiesNextProvider>

Usage: Use useReactiveCookiesNext() or individual hooks like useReactiveGetCookie().

import { CookiesNextProvider } from "cookies-next";

export function Providers({ children }) {
    return <CookiesNextProvider pollingOptions={{ enabled: true, intervalMs: 1000 }}>{children}</CookiesNextProvider>;
}

In Server Components, you can perform read-only operations using the cookies function from next/headers.

Warning: You cannot update or delete cookies directly within a Server Component.

import { getCookie, getCookies, hasCookie } from 'cookies-next/server';
import { cookies } from 'next/headers';

export const ServerComponent = async () => {
  const value = await getCookie('test', { cookies });
  const allCookies = await getCookies({ cookies });
  const exists = await hasCookie('test', { cookies });

  return <div>...</div>;
};

In Server Actions, you can perform all operations (set, get, delete) using the cookies function from next/headers.

'use server';

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

export async function serverAction() {
  await setCookie('test', 'value', { cookies });
  await deleteCookie('test', { cookies });
  await getCookie('test', { cookies });
  await getCookies({ cookies });
  await hasCookie('test', { cookies });
}

In Next.js Middleware, use cookies-next/server and pass the req and res objects.

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { getCookie, setCookie, deleteCookie, hasCookie, getCookies } from 'cookies-next/server';

export async function middleware(req: NextRequest) {
  const res = NextResponse.next();
  await setCookie('test', 'value', { res, req });
  await hasCookie('test', { req, res });
  await deleteCookie('test', { res, req });
  await getCookie('test', { res, req });
  await getCookies({ res, req });

  return res;
}

When using CookiesNextProvider and reactive hooks, you can manually trigger a revalidation of the cookie state (e.g., after a fetch operation that sets cookies on the server). Use revalidateCookiesState from useReactiveCookiesNext() or the useRevalidateCookieStore() hook.

import { useReactiveCookiesNext } from 'cookies-next';

function ClientComponent() {
  const { revalidateCookiesState } = useReactiveCookiesNext();

  useEffect(() => {
    fetchData({ onSuccess: revalidateCookiesState });
  }, []);
}

The import path depends on your Next.js version and the environment (client vs server):

Next.js 15+ Client-side:

import { getCookie, setCookie, ... } from 'cookies-next/client';

Next.js 15+ Server-side:

import { getCookie, setCookie, ... } from 'cookies-next/server';

Next.js 15+ Root Import (Automatic detection):

import { getCookie, setCookie, ... } from 'cookies-next';

Next.js 12.2.0 to 13.x:

import { getCookie, setCookie, ... } from 'cookies-next';

import { getCookie, getCookies, setCookie, deleteCookie, hasCookie } from 'cookies-next';

In API Routes, pass the req and res objects to the cookies-next/server functions, or use the cookies function from next/headers.

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

export async function GET(req: NextRequest) {
  const res = new NextResponse();
  await setCookie('test', 'value', { res, req });
  await getCookie('test', { res, req });
  await getCookies({ res, req });
  await deleteCookie('test', { res, req });
  await hasCookie('test', { req, res });

  return res;
}

Install the appropriate version based on your Next.js version:

For Next.js 15 and above:

npm install --save cookies-next@latest

For Next.js 12.2.0 to 14.x:

npm install --save cookies-next@4.3.0

When working with the Next.js App Router (Server Components or API Routes), you must pass the cookies function from next/headers into the options parameter of cookies-next methods to ensure compatibility with the App Router's cookie management system.

Note: Attempting to use these server-side functions on the client side will throw an error. For client-side cookie management, use cookies-next/client instead.

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

export async function MyServerComponent() {
  // Reading
  const val = await getCookie('my-key', { cookies });
  
  // Writing
  await setCookie('my-key', 'my-value', { cookies });
}

To manage and synchronize cookie state across your React client components, wrap your application (or a specific component tree) with the CookieProvider.

This provider maintains a local state of cookies and provides a context for interacting with them. It also supports optional polling via pollingOptions to keep the local state synchronized with the actual browser cookies using useCookiesPolling.

Key features of the provider:

• State Synchronization: Automatically initializes state from getCookies() on mount.
• Polling: Can be configured to poll for cookie changes.
• Context Access: Exposes a set of methods (set, get, getAll, has, delete, revalidateCookiesState) via CookieContext.

import { CookieProvider } from 'cookies-next';

function App() {
  return (
    <CookieProvider>
      <YourComponent />
    </CookieProvider>
  );
}

In client components, you can use individual hooks for each operation or a single hook that returns all functions.

Note: To avoid hydration mismatch errors, it is highly recommended to use these functions inside useEffect or event handlers. If using them in useEffect, include the hook function in the dependency array.

import { useGetCookies, useSetCookie, useHasCookie, useDeleteCookie, useGetCookie } from 'cookies-next';

function ClientComponent() {
  const setCookie = useSetCookie();
  const hasCookie = useHasCookie();
  const deleteCookie = useDeleteCookie();
  const getCookies = useGetCookies();
  const getCookie = useGetCookie();

  setCookie('key', 'value');

  return (
    <div>
      <p>hasCookie - {JSON.stringify(hasCookie('key'))}</p>
      <button onClick={() => deleteCookie('key')}>delete</button>
    </div>
  );
}

Standard API for managing cookies:

• setCookie(key, value, options): Sets a cookie.
• getCookie(key, options): Retrieves a specific cookie.
• getCookies(options): Retrieves all cookies.
• hasCookie(key, options): Checks if a cookie exists.
• deleteCookie(key, options): Deletes a cookie.

setCookie('key', 'value', options);
const value = getCookie('key', options);
const cookies = getCookies(options);
const exists = hasCookie('key', options);
deleteCookie('key', options);