wealth/.claude/skills/front-end-architect/references/lib-cookie.md

6.8 KiB

Cookie lib (packages/libs/src/cookie)

One small CookieAdapter class over document.cookie: get, set, and remove with encoding, safe defaults (path=/, SameSite=Lax, Secure), and per-call options. Browser only; framework-agnostic; no dependency (no js-cookie).

Contents: What cookies are for · Structure · Types · API · Keys · Browser only · Server side · Usage · Acceptance checklist

What cookies are for

  • Only small values the server must see on the request: theme (so the server renders it without a flash), a locale preference, and the consent choice. A locale cookie never decides the locale of an indexable page, which its URL decides (ui-rules.md), and no cookie picks the mobile or desktop template, which comes from the User-Agent's device class only (b2c-b2b.md).
  • Every cookie is sent with every request to its domain and path and holds about 4 KB. Anything the server doesn't need goes to local storage (lib-local-storage.md).
  • Never auth tokens. Auth cookies are HttpOnly, set and rotated by the server, and JavaScript can't and mustn't read them (see lib-http.md, Refresh token). Never secrets or personal data.

Structure

packages/libs/src/cookie/
├── cookie.ts      # CookieAdapter class and the shared `cookie` instance
├── types.ts       # CookieAdapterAbstraction, CookieOptions
├── constants.ts   # DEFAULT_COOKIE_OPTIONS
└── index.ts
  • index.ts exports CookieAdapter, cookie, DEFAULT_COOKIE_OPTIONS, and the types CookieAdapterAbstraction and CookieOptions. Nothing goes in server.ts: the lib is browser-only.
  • Import by subpath: import { cookie } from '@project/libs/cookie'.

Types

interface CookieOptions {
  path?: string; // default '/'
  domain?: string; // default: none (current host only); set it to share with subdomains, e.g. '.example.com'
  maxAgeDays?: number; // lifetime in days; omit for a session cookie
  sameSite?: 'Strict' | 'Lax' | 'None'; // default 'Lax'
  secure?: boolean; // default true; forced to true when sameSite is 'None'
}

interface CookieAdapterAbstraction {
  get(key: string): string | null;
  set(key: string, value: string, options?: CookieOptions): void;
  remove(key: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
}

API

  • get(key) returns the decoded value, or null when the cookie doesn't exist. It finds the encodeURIComponent(key)= entry in document.cookie split by '; ' and decodes the rest, so values containing = stay whole. A value with broken percent-encoding (written by other code) is returned raw instead of throwing.
  • set(key, value, options?) writes key=value with encodeURIComponent on both, plus the attributes:
    • Options merge in this order: DEFAULT_COOKIE_OPTIONS → configure defaults → call options.
    • maxAgeDays becomes max-age in seconds (Math.floor(days * 24 * 60 * 60)); without it the cookie is a session cookie.
    • sameSite: 'None' always adds Secure, because browsers reject it otherwise.
  • remove(key, options?) writes the cookie empty with max-age=0. It must use the same path and domain the cookie was set with, or the browser keeps the original. Defaults come from configure, so keep them the same for set and remove.
  • configure(defaults: CookieOptions) sets the defaults once, in the app's bootstrap. It only stores options and never touches document, so it's safe in bootstrap.client.ts during SSR. For example, cookie.configure({ secure: clientEnv.NEXT_PUBLIC_COOKIE_SECURE }), from the app's env, lets local development over plain http on a non-localhost host turn Secure off.
  • There is no public mutable options property: on a shared instance, any code could change every other caller's cookies at any time. Per-call differences go in the call's options.
  • The shared instance is export const cookie = new CookieAdapter();. Create another CookieAdapter only in tests.

Keys

  • Cookie names are constants in the owning project's constants.ts (LOCALE_COOKIE, THEME_COOKIE), never string literals at call sites.
  • Names are a contract with the server: proxy.ts, Server Components, and the back end read the same names, so renaming one is a breaking change.
  • Names are not prefixed automatically (unlike local-storage keys), because the server reads them by their exact name.

Browser only

  • Every method except configure checks typeof document === 'undefined' and throws a clear error ("cookie is browser-only; on the server read cookies with next/headers") instead of the unclear "document is not defined".
  • Call it only in event handlers, effects, actions, and client bootstrap code. Never during render and never at module top level: client components also render on the server, and a value read during render differs between server and browser, which breaks hydration.

Server side

  • Server code reads cookies with cookies() from next/headers (Server Components, Route Handlers, Server Functions) or request.cookies in proxy.ts, inside the app or platform. The lib never imports Next.js.
  • Server Components can't set cookies. Set them in proxy.ts, a Route Handler, or a Server Function on the server, or with cookie.set in the browser.
  • A value the page needs while rendering (theme) is read on the server and passed down as a prop. The browser writes it with cookie.set when the user changes it, then refreshes or updates the UI.

Usage

Bootstrap (bootstrap.client.ts):

cookie.configure({ secure: clientEnv.NEXT_PUBLIC_COOKIE_SECURE });

features/preferences/actions/change-theme/actions.ts

import { cookie } from '@project/libs/cookie';
import { usePreferencesStore } from '../../../../stores/preferences';
import { THEME_COOKIE, THEME_COOKIE_MAX_AGE_DAYS } from '../../constants';
import type { Theme } from '../../entities/theme';

export function changeTheme(theme: Theme): 'ok' {
  cookie.set(THEME_COOKIE, theme, { maxAgeDays: THEME_COOKIE_MAX_AGE_DAYS });
  usePreferencesStore.getState().setTheme(theme);
  return 'ok';
}

Acceptance checklist

For building or changing the lib:

[ ] set, get, and remove round-trip a value, including values with "=", ";", spaces, and non-Latin text (e.g. Persian)
[ ] get returns null for a missing cookie and doesn't match a cookie whose name only starts with the key ("theme" vs "theme-v2")
[ ] A value with broken percent-encoding is returned raw, not thrown
[ ] maxAgeDays writes the right max-age; no maxAgeDays writes a session cookie
[ ] sameSite 'None' always writes Secure
[ ] Call options win over configure defaults, which win over DEFAULT_COOKIE_OPTIONS
[ ] remove with the configured path and domain deletes the cookie
[ ] get, set, and remove throw the clear browser-only error on the server; configure doesn't