cookies-next

A versatile cookie management library for Next.js applications, supporting both client-side and server-side operations.

Features

• Works on client-side, server-side rendering, and API routes
• Supports Next.js 13+ App Router and Server Components
• TypeScript compatible
• Lightweight and easy to use

Installation

For Next.js versions 15 and above, use the latest version of cookies-next:

1npm install --save cookies-next@latest

For Next.js versions 12.2.0 to 14.x, use cookies-next version 4.3.0:

1npm install --save cookies-next@4.3.0

Usage

Importing

For Next.js 15+:

1// For client-side usage
2import {
3  getCookie,
4  getCookies,
5  setCookie,
6  deleteCookie,
7  hasCookie,
8  useGetCookies,
9  useSetCookie,
10  useHasCookie,
11  useDeleteCookie,
12  useGetCookie,
13} from 'cookies-next/client';
14
15// For server-side usage
16import { getCookie, getCookies, setCookie, deleteCookie, hasCookie } from 'cookies-next/server';

Also, you can leave the decision of which import to use to the the library itself, by importing from the root:

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

For Next.js 12.2.0 to 13.x:

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

Basic Operations

Set a cookie

1setCookie('key', 'value', options);

Get a cookie

1const value = getCookie('key', options);

Get all cookies

1const cookies = getCookies(options);

Check if a cookie exists

1const exists = hasCookie('key', options);

Delete a cookie

1deleteCookie('key', options);

Client-side Usage

Hooks

Using separate hook for each cookie function:

1'use client';
2
3import { useGetCookies, useSetCookie, useHasCookie, useDeleteCookie, useGetCookie } from 'cookies-next';
4
5function ClientComponent() {
6  const setCookie = useSetCookie();
7  const hasCookie = useHasCookie();
8  const deleteCookie = useDeleteCookie();
9  const getCookies = useGetCookies();
10  const getCookie = useGetCookie();
11
12  setCookie('key', 'value');
13
14  return (
15    <div>
16      <p>hasCookie - {JSON.stringify(hasCookie('key'))}</p>
17      <p>getCookies - {JSON.stringify(getCookies)}</p>
18      <p>getCookie - {getCookie('key')}</p>
19      <button type="button" onClick={() => deleteCookie('key')}>
20        deleteCookie
21      </button>
22    </div>
23  );
24}

Using one hook that returns all of the cookie functions:

1'use client';
2
3import { useCookiesNext } from 'cookies-next';
4
5function ClientComponent() {
6  const { setCookie, hasCookie, deleteCookie, getCookies, getCookie } = useCookiesNext();
7
8  setCookie('key', 'value');
9
10  return (
11    <div>
12      <p>hasCookie - {JSON.stringify(hasCookie('key'))}</p>
13      <p>getCookies - {JSON.stringify(getCookies)}</p>
14      <p>getCookie - {getCookie('key')}</p>
15      <button type="button" onClick={() => deleteCookie('key')}>
16        deleteCookie
17      </button>
18    </div>
19  );
20}

If you are going to perform actions on cookies inside a useEffect, make sure to add the cookie function returned from the hook to the dependency array.

1const getCookies = useGetCookies();
2
3useEffect(() => {
4  console.log('getCookies', getCookies());
5}, [getCookies]);

Client functions

1'use client';
2
3import { getCookies, setCookie, deleteCookie, getCookie } from 'cookies-next/client';
4
5function ClientComponent() {
6  /* 
7 ❗❗❗ In a client component, it's highly recommended to use cookies-next functions within useEffect or in event handlers; otherwise, you might encounter hydration mismatch errors. - 
8 https://react.dev/link/hydration-mismatch.   
9 */
10
11  useEffect(() => {
12    getCookies();
13    getCookie('key');
14    setCookie('key', 'value');
15    deleteCookie('key');
16    hasCookie('key');
17  }, []);
18
19  const handleClick = () => {
20    getCookies();
21    getCookie('key');
22    setCookie('key', 'value');
23    deleteCookie('key');
24    hasCookie('key');
25  };
26
27  /* .... */
28}

Server-side Usage (App Router)

In Server Components:

1import { getCookie, getCookies, hasCookie } from 'cookies-next/server';
2import { cookies } from 'next/headers';
3
4export const ServerComponent = async () => {
5  // Read-only operations in Server Components
6  const value = await getCookie('test', { cookies });
7  const allCookies = await getCookies({ cookies });
8  const exists = await hasCookie('test', { cookies });
9
10  // Note: It's not possible to update cookies in Server Components
11  ❌ await setCookie("test", "value", { cookies }); // Won't work
12  ❌ await deleteCookie('test', { cookies }); // Won't work
13
14  return <div>...</div>;
15};

In Server Actions:

1'use server';
2
3import { cookies } from 'next/headers';
4import { setCookie, deleteCookie, getCookie, getCookies, hasCookie } from 'cookies-next/server';
5
6export async function serverAction() {
7  await setCookie('test', 'value', { cookies });
8  await deleteCookie('test', { cookies });
9  await getCookie('test', { cookies });
10  await getCookies({ cookies });
11  await hasCookie('test', { cookies });
12}

API Routes (App Router)

1import { cookies } from 'next/headers';
2import { NextRequest, NextResponse } from 'next/server';
3import { deleteCookie, getCookie, setCookie, hasCookie, getCookies } from 'cookies-next/server';
4
5export async function GET(req: NextRequest) {
6  const res = new NextResponse();
7  await setCookie('test', 'value', { res, req });
8  await getCookie('test', { res, req });
9  await getCookies({ res, req });
10  await deleteCookie('test', { res, req });
11  await hasCookie('test', { req, res });
12
13  // Using cookies function
14  await setCookie('test1', 'value', { cookies });
15  await getCookie('test1', { cookies });
16  await getCookies({ cookies });
17  await deleteCookie('test1', { cookies });
18  await hasCookie('test1', { cookies });
19
20  return res;
21}

Middleware

1import { NextResponse } from 'next/server';
2import type { NextRequest } from 'next/server';
3import { getCookie, setCookie, deleteCookie, hasCookie, getCookies } from 'cookies-next/server';
4
5export async function middleware(req: NextRequest) {
6  const res = NextResponse.next();
7  await setCookie('test', 'value', { res, req });
8  await hasCookie('test', { req, res });
9  await deleteCookie('test', { res, req });
10  await getCookie('test', { res, req });
11  await getCookies({ res, req });
12
13  return res;
14}

API

setCookie(key, value, options)

Sets a cookie.

1setCookie('key', 'value', options);

getCookie(key, options)

Retrieves a specific cookie.

1const value = getCookie('key', options);

getCookies(options)

Retrieves all cookies.

1const cookies = getCookies(options);

hasCookie(key, options)

Checks if a cookie exists.

1const exists = hasCookie('key', options);

deleteCookie(key, options)

Deletes a cookie.

1deleteCookie('key', options);

Options

• req: Required for server-side operations (except when using cookies function)
• res: Required for server-side operations (except when using cookies function)
• cookies: Function from next/headers, used in App Router for server-side operations
• domain: Specifies the cookie's domain
• path: Specifies the cookie's path
• maxAge: Specifies the cookie's maximum age in seconds
• httpOnly: Sets the HttpOnly flag
• secure: Sets the Secure flag
• sameSite: Sets the SameSite attribute ('strict', 'lax', or 'none')

For more detailed options, refer to the cookie specification.

License

MIT