This version (v0.7) has not been published to npm yet.
Skip to content

Reference / @getenginex/sdk-next / nextCookieTokenStore

nextCookieTokenStore() ​

nextCookieTokenStore(options?): TokenStore

Cookie TokenStore, for the browser: the same session is readable on the server with readCookieTokenStore() from @getenginex/sdk-next/server (authenticated SSR). Optional: the SDK default remains localStorageTokenStore.

  • Cookie: <name>=<tokens>; Path=/; SameSite=Lax; Secure, without Domain (only the operator's domain) and without HttpOnly: the session refresh and the WebSocket ?token= need the token in JavaScript.
  • Security: as with localStorage, an XSS reads the token. The cookie still goes on every request to the app's domain (including navigations coming from another site, with SameSite=Lax): the app's server must only use it for reads (GET), never to perform actions on behalf of the cookie (CSRF).
  • Logs: the refresh token now goes on every request to the Next server (and to the proxies and CDN in front of it). Take the cookie out of the access logs (redaction of the Cookie header or of the cookie name).
  • HTTPS only: with Secure, every browser silently discards the cookie on an HTTP origin that is not localhost (LAN IP, http://dev.domain:port). On http://localhost, Chrome (89+) and Firefox (75+) accept the Secure cookie; other browsers, such as Safari, may not (see the Secure note on Set-Cookie, in MDN). The browser also discards cookies above ~4 KB (both tokens go in a single cookie). In both cases, set checks whether the cookie stuck and, if not, warns with console.warn (without the token) and does not throw; the login is not stored and the client stays without a session. The check is skipped when the page is outside the cookie's path (the browser does not show it there) and with maxAge: 0 (the cookie is born expired).
  • Tabs: with the Cookie Store API (cookieStore), it notifies subscribers when another tab changes the cookie; without it, only the changes made by this store.
  • Outside the browser (SSR of a Client Component): get() returns null and set/clear do not store anything, so no session stays in memory between server requests. On the server, use readCookieTokenStore().

The cookie value never appears in errors: a malformed cookie becomes "no session".

Parameters ​

options? ​

NextCookieTokenStoreOptions = {}

Cookie name, lifetime and Path.

Returns ​

TokenStore

A TokenStore for createEnginexClient({ tokenStore }).

Throws ​

CONFIGURATION_ERROR if name is not usable as a cookie name.

Example ​

ts
'use client'
import { createEnginexClient } from '@getenginex/sdk'
import { nextCookieTokenStore } from '@getenginex/sdk-next'

export const enginex = createEnginexClient({
  tokenStore: nextCookieTokenStore({ maxAge: 60 * 60 * 24 * 30 }),
})