Skip to Content

Session storage

The default client stores its session in memory. Choose a store when a session should survive a page reload.

import { createCustomerClient, localStorageSessionStore } from '@preternatural-js/client-sdk' const client = createCustomerClient({ environment: 'production', projectId: 'your-project-id', sessionStore: localStorageSessionStore() })

The store includes access and refresh tokens. Use it only in a trusted application origin; do not place admin keys or provider credentials in it.

Choose a lifetime

StoreLifetimeOther tabs
No storeThis client instanceIndependent sessions
sessionStorageSessionStore()Reloads in the current tabNo subscription to other tabs
localStorageSessionStore()Reloads and browser restartsAdopts storage changes from the same origin

Import either helper from @preternatural-js/client-sdk. A custom { key: 'my-app-session' } prefix separates applications sharing one origin. Keys are scoped by project and Live/Sandbox mode.

On construction, an explicit session or synthetic authentication takes precedence over storage. Otherwise the client reads the store once. A stored session can therefore be adopted before an identity-token callback is called.

Cross-tab changes

A local-storage sign-out or account change is adopted by other tabs. Replacing the customer, refresh token, project or mode ends requests from the previous session with CustomerSessionChangedError. Renewing only its access token does not end those requests.

client.session.clear() clears this client’s stored session. This is local sign-out; it is not a request to delete the customer or revoke all their other sessions.

Storage failures and custom stores

Without window, or when storage is unavailable, browser helpers read null and ignore writes. Invalid stored data is removed when possible. Do not assume persistence succeeded merely because sign-in succeeded.

A CustomerSessionStore implements synchronous read(scope), write(session, scope) and clear(scope). Optional subscribe(onChange, scope) reports changes made elsewhere and returns an unsubscribe function. Keep a store’s project/mode isolation intact. See Authentication for renewal and access-end states.