Get Started- Complete documentation overview

How ShipSafe handles cookies, and how to turn on a consent banner when you add non-essential analytics.

Default (essential only)

By default ShipSafe sets essential cookies only. config.cookies.nonEssentialEnabled is false, so no consent banner is shown on / or elsewhere.

CookieRole
sessionFirebase session cookie (httpOnly); set on login, ~5 days, cleared on logout
csrf_tokenCSRF httpOnly cookie
csrf_token_clientCSRF value readable by JS for the x-csrf-token header
firebase_tokenLegacy ID-token cookie name (cleared on logout; do not set or accept for auth)

Public policy page: /cookies (src/app/cookies/page.tsx).

Preference storage (when the banner is enabled): localStorage key from config.cookies.storageKey (default shipsafe_cookie_prefs), shape { analytics: boolean, updatedAt: string }.

Config

cookies: {
  nonEssentialEnabled: false, // flip true when you add analytics
  policyPath: "/cookies",
  storageKey: "shipsafe_cookie_prefs",
},

Components / helpers

PiecePath
CookieConsentsrc/components/ui/CookieConsent.tsx — mounted via ClientLayout in root layout
getCookiePrefs / writeCookiePrefssrc/features/cookies/prefs.ts

Non-essential / analytics

When you add Plausible, GA, or similar:

  1. Set config.cookies.nonEssentialEnabled to true
  2. Expand CSP allowlists for that vendor (Security Headers)
  3. Gate scripts with getCookiePrefs(config.cookies.storageKey)?.analytics === true
  4. Clear localStorage for the storage key when testing the banner

Until then, leave nonEssentialEnabled false.

Related