next-cookies-universal

🍪 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

npm i next-cookies-universal

Yarn

yarn add next-cookies-universal

Usage

Initialize

import Cookies from 'next-cookies-universal';


const ServerCookies = Cookies('server');
// or
const ClientCookies = Cookies('client');

Client Component

'use client';

import Cookies from 'next-cookies-universal';


const MyClientComponent = () => {
  const cookies = Cookies('client');

  const handleClick = () => {
    cookies.set('my_token', 'my_token_value');
  };

  const handleClickWithExpiry = () => {
    // Set cookie with maxAge (expires in 1 hour)
    cookies.set('my_token', 'my_token_value', {
      maxAge: 60 * 60, // 1 hour in seconds
      path: '/'
    });
  };

  const handleClickWithExpiresDate = () => {
    // Set cookie with specific expiration date
    const expiryDate = new Date();
    expiryDate.setDate(expiryDate.getDate() + 7); // 7 days from now
    cookies.set('my_token', 'my_token_value', {
      expires: expiryDate,
      path: '/'
    });
  };

  return (
    <div>
      <button onClick={handleClick}>
        Click to set cookies
      </button>
      <button onClick={handleClickWithExpiry}>
        Click to set cookies with maxAge
      </button>
      <button onClick={handleClickWithExpiresDate}>
        Click to set cookies with expires date
      </button>
    </div>
  );
};

Server Component

import Cookies from 'next-cookies-universal';


const MyServerComponent = async() => {
  const cookies = Cookies('server');
  const myToken = await cookies.get('my_token');

  const data = await fetch('http://your.endpoint', {
    headers: {
      Authentication: `Bearer ${myToken}`
    }
  }).then(response => response.json());

  return (
    <div>
      <p>Cookies Value: <strong>{myToken}</strong></p>
      <code>
        {JSON.stringify(data)}
      </code>
    </div>
  );
};

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.

import Cookies from 'next-cookies-universal';


const MyServerComponent = async() => {
  const cookies = Cookies('server');

  /** you should not to do like this!
   * please read Server Actions reference if you want to set the cookies through Server.
   */
  await cookies.set('my_token', 'my_token_value');

  const myToken = await cookies.get('my_token');

  return (
    <div>
      <p>Cookies Value: <strong>{myToken}</strong></p>
      <code>
        {JSON.stringify(data)}
      </code>
    </div>
  );
};

Server Actions

With Server Component

import Cookies from 'next-cookies-universal';

async function setFromAction(formData: FormData) {
  'use server';

  const cookies = Cookies('server');
  await cookies.set('my_token', formData.get('cookie-value'));
}

function Form() {
  return (
    <div>
      <form action={setFromAction}>
        <input type="text" name="cookie-value" />
        <div>
          <button type="submit">
            Set Your cookies
          </button>
        </div>
      </form>
    </div>
  );
}

With Client Component

/** action.ts */
'use server';

export async function setFromAction(formData: FormData) {
  const cookies = Cookies('server');
  await cookies.set('my_token', formData.get('cookie-value'));
}

/** Form.tsx */
'use client';
import { setFromAction } from './action.ts';

function Form() {
  /** client logic */
  return (
    <div>
      <form action={setFromAction}>
        <input type="text" name="cookie-value" />
        <div>
          <button type="submit">
            Set Your cookies
          </button>
        </div>
      </form>
    </div>
  );
}

Cookie Options

Setting Cookies with Expiration

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

'use client';

import Cookies from 'next-cookies-universal';

const cookies = Cookies('client');

// Set cookie that expires in 1 hour using maxAge
cookies.set('session_token', 'abc123', {
  maxAge: 60 * 60, // 1 hour in seconds
  path: '/'
});

// Set cookie that expires in 1 day using expires Date
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
cookies.set('user_preference', 'dark_mode', {
  expires: tomorrow, // expires tomorrow
  path: '/',
  secure: true,
  sameSite: 'strict'
});

// Set cookie that expires in 1 year using maxAge
cookies.set('remember_me', 'true', {
  maxAge: 365 * 24 * 60 * 60, // 1 year in seconds
  path: '/'
});

// Set cookie with specific expiration date
const specificDate = new Date('2024-12-31T23:59:59Z');
cookies.set('campaign_banner', 'hidden', {
  expires: specificDate, // expires on specific date
  path: '/'
});

Server Actions with Cookie Options

import Cookies from 'next-cookies-universal';

async function setTokenWithExpiry(formData: FormData) {
  'use server';

  const cookies = Cookies('server');
  const token = formData.get('token');

  // Set cookie with 7 days expiration using maxAge
  await cookies.set('auth_token', token, {
    maxAge: 7 * 24 * 60 * 60, // 7 days in seconds
    path: '/',
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict'
  });

  // Set cookie with specific expiration date using expires
  const sessionExpiry = new Date();
  sessionExpiry.setHours(sessionExpiry.getHours() + 2); // 2 hours from now
  await cookies.set('session_id', 'session_123', {
    expires: sessionExpiry,
    path: '/',
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict'
  });
}

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:
  • 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: 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

/** parameter to initialize the Cookies() */
export type ICookiesContext = 'server'|'client';

/** Client cookies interface (synchronous) */
export interface IClientCookies {
  set<T = string>(
    key: string,
    value: T,
    options?: ICookiesOptions
  ): void;

  get<T = string>(key: string): T;

  remove(key: string, options?: ICookiesOptions): void;

  has(key: string): boolean;

  clear(): void;
}

/** Server cookies interface (asynchronous) */
export interface IServerCookies {
  set<T = string>(
    key: string,
    value: T,
    options?: ICookiesOptions
  ): Promise<void>;

  get<T = string>(key: string): Promise<T>;

  remove(key: string, options?: ICookiesOptions): Promise<void>;

  has(key: string): Promise<boolean>;

  clear(): Promise<void>;
}

/** Function overloads */
function Cookies(context: 'client'): IClientCookies;
function Cookies(context: 'server'): 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