🍪 Cookies Universal for NextJS App Route

An utility that can help you to handle the Cookies in NextJS App Route with every context (both Server or Client) 🍪🔥

All supported to NextJS App Route

• ✅ Server Component and Server Actions Based on next/headers cookies
• ✅ Client Component Based on js-cookie

Table of Contents

• 🍪 Cookies Universal for NextJS App Route
• Table of Contents
• Live Demo
• Getting Started
  • Install
    • NPM
    • Yarn
  • Usage
    • Initialize
    • Client Component
    • Server Component
    • Server Actions
      • With Server Component
      • With Client Component
• Cookie Options
  • Setting Cookies with Expiration
  • Server Actions with Cookie Options
  • Important Notes
• API Reference
• Publishing
• License
• Feedbacks and Issues
• Support
  • Global
  • Indonesia

Live Demo

You can see Live Demo here

Getting Started

Install

NPM

1npm i next js-cookie next-cookies-universal

Yarn

1yarn add next js-cookie next-cookies-universal

Usage

Initialize

1import Cookies from 'next-cookies-universal';
2
3// Both client and server contexts require await for initialization
4const ClientCookies = await Cookies('client');
5const ServerCookies = await Cookies('server');

Note: Both client and server contexts require await for initialization to comply with Next.js 15's stricter cookie handling. Once initialized, all cookie operations (get, set, remove, has, clear) are synchronous.

Direct Import (Alternative)

You can also import client and server cookies directly:

1import { CookiesClient, CookiesServer } from 'next-cookies-universal';
2
3// Direct client cookies (no await required)
4const clientCookies = CookiesClient();
5
6// Direct server cookies (requires await for initialization)
7const serverCookies = await CookiesServer();

Note: CookiesClient() can be used synchronously without await, while CookiesServer() still requires await for initialization. Both provide the same functionality as the main Cookies() function but offer better code clarity and developer experience.

Client Component

1'use client';
2
3import Cookies from 'next-cookies-universal';
4// Or use direct import: import { CookiesClient } from 'next-cookies-universal';
5import { useEffect, useState } from 'react';
6
7
8const MyClientComponent = () => {
9  const [cookies, setCookies] = useState(null);
10
11  useEffect(() => {
12    const initCookies = async () => {
13      const cookieInstance = await Cookies('client');
14      // Or with direct import: const cookieInstance = CookiesClient();
15      setCookies(cookieInstance);
16    };
17    initCookies();
18  }, []);
19
20  const handleClick = () => {
21    if (cookies) {
22      cookies.set('my_token', 'my_token_value');
23    }
24  };
25
26  const handleClickWithExpiry = () => {
27    if (cookies) {
28      // Set cookie with maxAge (expires in 1 hour)
29      cookies.set('my_token', 'my_token_value', {
30        maxAge: 60 * 60, // 1 hour in seconds
31        path: '/'
32      });
33    }
34  };
35
36  const handleClickWithExpiresDate = () => {
37    if (cookies) {
38      // Set cookie with specific expiration date
39      const expiryDate = new Date();
40      expiryDate.setDate(expiryDate.getDate() + 7); // 7 days from now
41      cookies.set('my_token', 'my_token_value', {
42        expires: expiryDate,
43        path: '/'
44      });
45    }
46  };
47
48  return (
49    <div>
50      <button onClick={handleClick}>
51        Click to set cookies
52      </button>
53      <button onClick={handleClickWithExpiry}>
54        Click to set cookies with maxAge
55      </button>
56      <button onClick={handleClickWithExpiresDate}>
57        Click to set cookies with expires date
58      </button>
59    </div>
60  );
61};

Server Component

1import Cookies from 'next-cookies-universal';
2// Or use direct import: import { CookiesServer } from 'next-cookies-universal';
3
4
5const MyServerComponent = async() => {
6  const cookies = await Cookies('server');
7  // Or with direct import: const cookies = await CookiesServer();
8  const myToken = cookies.get('my_token');
9
10  const data = await fetch('http://your.endpoint', {
11    headers: {
12      Authentication: `Bearer ${myToken}`
13    }
14  }).then(response => response.json());
15
16  return (
17    <div>
18      <p>Cookies Value: <strong>{myToken}</strong></p>
19      <code>
20        {JSON.stringify(data)}
21      </code>
22    </div>
23  );
24};

Note: if you want to set cookies in Server, you not to allowed to set it on Server Component, you should do that in Server Actions.

1import Cookies from 'next-cookies-universal';
2
3
4const MyServerComponent = async() => {
5  const cookies = await Cookies('server');
6
7  /** you should not to do like this!
8   * please read Server Actions reference if you want to set the cookies through Server.
9   */
10  cookies.set('my_token', 'my_token_value');
11
12  const myToken = cookies.get('my_token');
13
14  return (
15    <div>
16      <p>Cookies Value: <strong>{myToken}</strong></p>
17      <code>
18        {JSON.stringify(data)}
19      </code>
20    </div>
21  );
22};

Server Actions

With Server Component

1import Cookies from 'next-cookies-universal';
2// Or use direct import: import { CookiesServer } from 'next-cookies-universal';
3
4async function setFromAction(formData: FormData) {
5  'use server';
6
7  const cookies = await Cookies('server');
8  // Or with direct import: const cookies = await CookiesServer();
9  cookies.set('my_token', formData.get('cookie-value'));
10}
11
12function Form() {
13  return (
14    <div>
15      <form action={setFromAction}>
16        <input type="text" name="cookie-value" />
17        <div>
18          <button type="submit">
19            Set Your cookies
20          </button>
21        </div>
22      </form>
23    </div>
24  );
25}

With Client Component

1/** action.ts */
2'use server';
3
4import Cookies from 'next-cookies-universal';
5// Or use direct import: import { CookiesServer } from 'next-cookies-universal';
6
7export async function setFromAction(formData: FormData) {
8  const cookies = await Cookies('server');
9  // Or with direct import: const cookies = await CookiesServer();
10  cookies.set('my_token', formData.get('cookie-value'));
11}

1/** Form.tsx */
2'use client';
3import { setFromAction } from './action.ts';
4
5function Form() {
6  /** client logic */
7  return (
8    <div>
9      <form action={setFromAction}>
10        <input type="text" name="cookie-value" />
11        <div>
12          <button type="submit">
13            Set Your cookies
14          </button>
15        </div>
16      </form>
17    </div>
18  );
19}

Cookie Options

Setting Cookies with Expiration

You can set cookies with various expiration options using the options parameter:

1'use client';
2
3import Cookies from 'next-cookies-universal';
4
5const cookies = Cookies('client');
6
7// Set cookie that expires in 1 hour using maxAge
8cookies.set('session_token', 'abc123', {
9  maxAge: 60 * 60, // 1 hour in seconds
10  path: '/'
11});
12
13// Set cookie that expires in 1 day using expires Date
14const tomorrow = new Date();
15tomorrow.setDate(tomorrow.getDate() + 1);
16cookies.set('user_preference', 'dark_mode', {
17  expires: tomorrow, // expires tomorrow
18  path: '/',
19  secure: true,
20  sameSite: 'strict'
21});
22
23// Set cookie that expires in 1 year using maxAge
24cookies.set('remember_me', 'true', {
25  maxAge: 365 * 24 * 60 * 60, // 1 year in seconds
26  path: '/'
27});
28
29// Set cookie with specific expiration date
30const specificDate = new Date('2024-12-31T23:59:59Z');
31cookies.set('campaign_banner', 'hidden', {
32  expires: specificDate, // expires on specific date
33  path: '/'
34});

Server Actions with Cookie Options

1import Cookies from 'next-cookies-universal';
2
3async function setTokenWithExpiry(formData: FormData) {
4  'use server';
5
6  const cookies = await Cookies('server');
7  const token = formData.get('token');
8
9  // Set cookie with 7 days expiration using maxAge
10  cookies.set('auth_token', token, {
11    maxAge: 7 * 24 * 60 * 60, // 7 days in seconds
12    path: '/',
13    httpOnly: true,
14    secure: process.env.NODE_ENV === 'production',
15    sameSite: 'strict'
16  });
17
18  // Set cookie with specific expiration date using expires
19  const sessionExpiry = new Date();
20  sessionExpiry.setHours(sessionExpiry.getHours() + 2); // 2 hours from now
21  cookies.set('session_id', 'session_123', {
22    expires: sessionExpiry,
23    path: '/',
24    httpOnly: true,
25    secure: process.env.NODE_ENV === 'production',
26    sameSite: 'strict'
27  });
28}

Important Notes

• maxAge: Specifies the cookie expiration time in seconds (relative to current time)
• expires: Specifies the exact date and time when the cookie should expire (absolute time)
• Client-side:
  • Cookies('client') requires await for initialization: const cookies = await Cookies('client')
  • CookiesClient() can be used synchronously: const cookies = CookiesClient()
  • Once initialized, all cookie operations are synchronous
  • The maxAge option is automatically converted to an expires Date object for compatibility with js-cookie
  • The expires option accepts a Date object directly
• Server-side:
  • Both Cookies('server') and CookiesServer() require await for initialization
  • Once initialized, all cookie operations are synchronous
  • Uses Next.js built-in cookie handling which supports both maxAge and expires directly
• Choosing between maxAge and expires:
  • Use maxAge for relative expiration (e.g., "expire in 1 hour")
  • Use expires for absolute expiration (e.g., "expire on December 31st")
• Security: Always use secure: true and appropriate sameSite settings in production

API Reference

1/** parameter to initialize the Cookies() */
2export type ICookiesContext = 'server'|'client';
3
4/** Client cookies interface (synchronous) */
5export interface IClientCookies {
6  set<T = string>(
7    key: string,
8    value: T,
9    options?: ICookiesOptions
10  ): void;
11
12  get<T = string>(key: string): T;
13
14  remove(key: string, options?: ICookiesOptions): void;
15
16  has(key: string): boolean;
17
18  clear(): void;
19}
20
21/** Server cookies interface (synchronous after initialization) */
22export interface IServerCookies {
23  initialize(): Promise<void>;
24
25  set<T = string>(
26    key: string,
27    value: T,
28    options?: ICookiesOptions
29  ): void;
30
31  get<T = string>(key: string): T;
32
33  remove(key: string, options?: ICookiesOptions): void;
34
35  has(key: string): boolean;
36
37  clear(): void;
38}
39
40/** Function overloads */
41function Cookies(context: 'client'): Promise<IClientCookies>;
42function Cookies(context: 'server'): Promise<IServerCookies>;
43
44/** Direct import functions */
45function CookiesClient(): IClientCookies;
46function CookiesServer(): Promise<IServerCookies>;

for ICookiesOptions API, we use CookieSerializeOptions from DefinetlyTyped

Publishing

• Before pushing your changes to Github, make sure that version in package.json is changed to newest version. Then run npm install for synchronize it to package-lock.json
• After your changes have been merged on branch main, you can publish the packages by creating new Relase here: https://github.com/gadingnst/next-cookies-universal/releases/new
• Create new tag, make sure the tag name is same as the version in package.json.
• You can write Release title and notes here. Or you can use auto-generated release title and notes.
• Click Publish Release button, then wait the package to be published.

License

next-cookies-universal is freely distributable under the terms of the MIT license.

Feedbacks and Issues

Feel free to open issues if you found any feedback or issues on next-cookies-universal. And feel free if you want to contribute too! 😄

Support

Global

Indonesia

• Trakteer
• Karyakarsa

---

Built with ❤️ by Sutan Gading Fadhillah Nasution on 2023