Sessions

Overview

The Storefront Core maintains stateful sessions to support user login along with baskets and wishlists for logged-in and guest users. Sessions are persistent with the data saved in a backing store so that no matter which web server handles the request, the user's session is consistent.

Session Storage

For storing the session data, the Storefront Core must be configured with a shared persistent storage provider. Unstorage is used under the hood to provide an abstraction over various providers.

The storefront.storage.session options are used to configure.

The in-memory storage provider should only be used for development.

Check Storefront Guide - Caching for detailed information on how to configure the session storage.

The session ID is saved in a cookie, named $session-${shopId} by default. Many of the cookie options can be configured, but the session cookie is always HttpOnly (not accessible to JavaScript on the page), and that cannot be changed.

Guest users

For guest users, the session ID is a random UUID, and for logged-in users, it's the user ID combined with a random UUID.

The session cookie is shop-based through the cookie name but attached to all requests and doesn't have any path scope.

The cookie's domain is also set to the current domain.

Configuration

The details of the session storage and cookie serialization can be controlled through the module configuration under the session property.

Parameter	Details
session.cookieName	`string` The name used for the session cookie. Defaults to `$session-${shopId}`.
session.sameSite	`'none' \| 'lax' \| 'strict'` The sameSite policy to use for the session cookie. Defaults to `'lax'`.
session.maxAge	`number` The default maxAge (in seconds) set on the session cookie and default TTL for session store. Defaults to 86400 (one day).
session.secret	`string \| string[]` The secret used for signing session cookies. If an array is passed, the last value is used for signing new cookies, but all values are used to verify cookies. This allows to rotate secrets in case your session secret get's leaked.
session.domain	`string` Controls the domain option on the session cookie

To allow for shop-specific behavior, these properties can be set at the top level of the configuration or inside a shop configuration. The settings will be merged with the shop session configuration having a higher priority.

The session configuration option session.provider is deprecated and should not be used anymore. It has been replaced by a dedicated storage.session configuration.

Example

let config = {
    session: {
        cookieName: '$session',
        sameSite: 'none',
        maxAge: 2419200, // four weeks in seconds
        secret: 'my-secret',
        domain: string,
    }
}

User-bound sessions

When a user logs in, the session ID is changed to include the user ID. Additionally, if the user had added items to their wishlist or basket while in a guest state, those items are merged into the logged-in user's wishlist and basket.

RPCContext methods

The RPCContext provides access to sessions for RPC Methods. They can read and update the data in the session, or destroy the session.

Method	Details
`context.user: ShopUser`	Provides access to the user data saved on the session
`context.updateUser: (user: ShopUser) => void`	Update the user data saved on the session
`context.destroySession: () => Promise<void>`	Destroys the current session, logging out the user in the process
`context.destroySessionsForUserId: (userId: number, sessionsToKeep?: string[]) => Promise<void>`	Destroys all sessions for a specific user, except for those listed in `sessionsToKeep`