or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-side.mdindex.mdreact-hooks.mdserver-side.md
tile.json

index.mddocs/

Cookies Next

Cookies Next is a versatile cookie management library for Next.js applications that provides unified cookie operations across both client-side and server-side environments. It automatically detects execution context and routes to appropriate implementations, supporting Next.js 13+ App Router, Server Components, API routes, and middleware.

Package Information

  • Package Name: cookies-next
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install cookies-next

Core Imports

For Next.js 15+ (recommended approach with explicit imports):

// Client-side usage
import {
  getCookie,
  getCookies,
  setCookie,
  deleteCookie,
  hasCookie,
  useGetCookies,
  useSetCookie,
  CookiesNextProvider,
} from 'cookies-next/client';

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

Auto-detecting imports (works in both contexts):

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

For CommonJS:

const { getCookie, getCookies, setCookie, deleteCookie, hasCookie } = require('cookies-next');

Basic Usage

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

// Set a cookie
setCookie('user-preference', 'dark-mode', { 
  maxAge: 30 * 24 * 60 * 60, // 30 days
  path: '/',
  secure: true,
  sameSite: 'strict'
});

// Get a cookie
const preference = getCookie('user-preference');

// Check if cookie exists
if (hasCookie('user-preference')) {
  console.log('User has set a preference');
}

// Delete a cookie
deleteCookie('user-preference');

Architecture

Cookies Next is built around several key components:

  • Auto-Detection: Main export functions automatically detect client vs server execution context
  • Context-Specific APIs: Separate client and server implementations optimized for each environment
  • React Integration: Comprehensive hooks for client-side React applications
  • Next.js Compatibility: Native support for App Router, Server Components, and traditional pages
  • Type Safety: Full TypeScript support with precise type definitions

Capabilities

Auto-Detecting Functions

Core cookie operations that automatically work in both client and server contexts by detecting the execution environment.

function getCookies(options?: OptionsType): TmpCookiesObj | Promise<TmpCookiesObj>;
function getCookie(key: string, options?: OptionsType): CookieValueTypes | Promise<CookieValueTypes>;
function setCookie(key: string, data: any, options?: OptionsType): void | Promise<void>;
function deleteCookie(key: string, options?: OptionsType): void | Promise<void>;
function hasCookie(key: string, options?: OptionsType): boolean | Promise<boolean>;

Client-Side Operations

Server-Side Operations

Async cookie operations specifically designed for Next.js server environments including Server Components, API routes, and middleware.

function getCookies(options?: OptionsType): Promise<TmpCookiesObj>;
function getCookie(key: string, options?: OptionsType): Promise<CookieValueTypes>;
function setCookie(key: string, data: any, options?: OptionsType): Promise<void>;
function deleteCookie(key: string, options?: OptionsType): Promise<void>;
function hasCookie(key: string, options?: OptionsType): Promise<boolean>;

Server-Side Operations

React Hooks

Comprehensive React hooks for client-side cookie management including both static and reactive variants with context provider support.

function useGetCookies(): () => TmpCookiesObj | undefined;
function useGetCookie(): (key: string, options?: OptionsType) => CookieValueTypes;
function useSetCookie(): (key: string, data: any, options?: OptionsType) => void;
function useDeleteCookie(): (key: string, options?: OptionsType) => void;
function useHasCookie(): (key: string, options?: OptionsType) => boolean;
function useCookiesNext(): CookiesNextHookResult;

React Hooks

Core Types

type OptionsType = HttpContext | NextContext;

interface HttpContext extends SerializeOptions {
  req?: IncomingMessage & {
    cookies?: TmpCookiesObj;
  };
  res?: ServerResponse;
}

type NextContext = {
  req?: NextCookiesRequest;
  res?: NextCookiesResponse;
  cookies?: CookiesFn;
};

type TmpCookiesObj = { [key: string]: string } | Partial<{ [key: string]: string }>;
type CookieValueTypes = string | undefined;
type CookiesFn = typeof cookies;

interface NextCookiesRequest extends Request {
  get cookies(): RequestCookies;
}

interface NextCookiesResponse extends Response {
  get cookies(): ResponseCookies;
}

// Context-Related Types
type CookieState = TmpCookiesObj;

interface CookieContextType {
  cookies: CookieState;
  set: (key: string, data: any) => void;
  get: (key: string) => CookieValueTypes;
  getAll: () => TmpCookiesObj | undefined;
  has: (key: string) => boolean;
  delete: (key: string) => void;
  revalidateCookiesState: () => void;
}

interface CookieProviderProps {
  children: ReactNode;
  pollingOptions?: PollingOptions;
}

type PollingOptions = {
  enabled?: boolean;
  intervalMs?: number;
};

Cookie options inherit from the standard cookie library's SerializeOptions:

interface SerializeOptions {
  path?: string;
  expires?: Date;
  maxAge?: number;
  domain?: string;
  secure?: boolean;
  httpOnly?: boolean;
  sameSite?: boolean | 'lax' | 'strict' | 'none';
}

Utility Functions

Advanced utility functions for custom implementations and internal operations:

/**
 * Convert any value to string for cookie storage (JSON.stringify for objects)
 * @param value - Value to convert to string
 * @returns Stringified value
 */
function stringify(value: any): string;

/**
 * Decode URI components in cookie values
 * @param str - String to decode
 * @returns Decoded string
 */
function decode(str: string): string;

/**
 * Determine if code is running in client-side context
 * @param options - Context options to check
 * @returns True if client-side, false if server-side
 */
function isClientSide(options?: OptionsType): boolean;

/**
 * Get current rendering phase
 * @returns 'client' if in browser, 'server' if in Node.js
 */
function getRenderPhase(): 'client' | 'server';