@54ruum/cookies

Cookie utilities for 54ruum.com and its subdomains. This package provides cross-subdomain cookie management with a hardcoded domain for security.

Features

• Cross-subdomain cookies - Works on 54ruum.com, app.54ruum.com, shop.54ruum.com, etc.
• Hardcoded domain - Cannot be misused on other domains
• Visitor tracking - Persistent visitor IDs across subdomains
• Consent management - GDPR-compliant consent preferences
• SSR support - Works in both client and server environments
• TypeScript - Full type definitions included

Installation

npm install @54ruum/cookies
# or
pnpm add @54ruum/cookies
# or
yarn add @54ruum/cookies

Quick Start

Client-Side Usage

import { 
  setConsent, 
  getOrCreateVisitorId, 
  hasConsented 
} from "@54ruum/cookies";

// Handle cookie consent popup
function handleAcceptCookies() {
  setConsent({ 
    analytics: true, 
    preferences: true, 
    marketing: false 
  });
  
  const visitorId = getOrCreateVisitorId();
  console.log("Visitor ID:", visitorId);
}

// Check if consent popup should be shown
if (!hasConsented()) {
  showConsentPopup();
}

Server-Side Usage (SSR)

import { parseCookies, getVisitorId, getConsentFromCookies } from "@54ruum/cookies";

// React Router loader
export async function loader({ request }) {
  const cookies = parseCookies(request.headers.get("Cookie") || "");
  const visitorId = getVisitorId(cookies);
  const consent = getConsentFromCookies(cookies);
  
  return { 
    visitorId,
    shouldLoadAnalytics: consent?.analytics ?? false 
  };
}

API Reference

Visitor Tracking

getOrCreateVisitorId(): string

Get existing visitor ID or create a new one (client-side only).

const visitorId = getOrCreateVisitorId();

getVisitorId(cookies: ParsedCookies): string | null

Get visitor ID from parsed cookies (for server-side use).

const cookies = parseCookies(request.headers.get("Cookie") || "");
const visitorId = getVisitorId(cookies);

generateVisitorId(): string

Generate a new UUID-style visitor ID.

const newId = generateVisitorId();

Consent Management

setConsent(preferences: ConsentPreferences): void

Store user's cookie consent preferences.

setConsent({
  analytics: true,
  preferences: true,
  marketing: false,
});

getConsent(): ConsentPreferences | null

Get current consent preferences (client-side).

const consent = getConsent();
if (consent?.analytics) {
  initAnalytics();
}

hasConsented(): boolean

Check if user has given any consent.

if (!hasConsented()) {
  showConsentPopup();
}

getConsentFromCookies(cookies: ParsedCookies): ConsentPreferences | null

Get consent from parsed cookies (server-side).

const consent = getConsentFromCookies(parseCookies(cookieHeader));

Core Cookie Operations

setCookie(name: string, value: string, options?: CookieOptions): void

Set a cookie (automatically uses .54ruum.com domain).

setCookie("my_cookie", "value", { maxAge: 3600 });

getCookie(name: string): string | null

Get a cookie value by name.

const value = getCookie("my_cookie");

deleteCookie(name: string): void

Delete a cookie.

deleteCookie("my_cookie");

parseCookies(cookieString: string): ParsedCookies

Parse a cookie string into an object (for SSR).

const cookies = parseCookies(request.headers.get("Cookie") || "");

Constants

import { COOKIE_NAMES, COOKIE_MAX_AGE, COOKIE_DOMAIN } from "@54ruum/cookies";

COOKIE_DOMAIN      // ".54ruum.com"
COOKIE_NAMES.VISITOR_ID   // "ruum_vid"
COOKIE_NAMES.CONSENT      // "ruum_consent"
COOKIE_NAMES.PREFERENCES  // "ruum_prefs"
COOKIE_NAMES.SESSION      // "ruum_session"

COOKIE_MAX_AGE.VISITOR     // 2 years (in seconds)
COOKIE_MAX_AGE.CONSENT     // 1 year
COOKIE_MAX_AGE.PREFERENCES // 1 year
COOKIE_MAX_AGE.SESSION     // 7 days

Types

interface ConsentPreferences {
  analytics: boolean;
  preferences: boolean;
  marketing: boolean;
}

interface CookieOptions {
  maxAge?: number;
  path?: string;
  secure?: boolean;
  sameSite?: "strict" | "lax" | "none";
  httpOnly?: boolean;
}

type ParsedCookies = Record<string, string>;

Security

This package is designed to work exclusively on 54ruum.com and its subdomains. The domain is hardcoded and cannot be changed or overridden, preventing misuse on other domains.

Local Development

The package automatically detects localhost environments and skips the domain restriction, allowing cookies to work during local development:

• localhost
• 127.0.0.1
• 192.168.* (local network)
• *.local (mDNS)

In production on any *.54ruum.com domain, cookies are automatically shared across all subdomains.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

Local Development

For testing with other 54ruum projects before publishing:

# In this repo
npm link

# In consumer repo
npm link @54ruum/cookies

License

MIT