Documentation

Using a session

commercetools Frontend provides a session mechanism for its extensions. Action extensions can read and write the session, while data source and dynamic page handler extensions can only read the session.

You can write the session by setting the sessionData property on the response returned from the action extensions. Then, you can read the session from the sessionData property on the extension's incoming request object.

The session mechanism is meant for server functions. Frontend components can't access the session directly. If you only need to conserve data for the frontend, use cookies, local storage, or a similar mechanism.

Write the session

The Action extensions receives the Request and Response objects as function argument. The mechanics to write the session works as follows:

  1. The action code ensures to have properly initialized sessionData.
  2. During the execution of the action, the session data is updated (in this case, the value 42 is stored).
  3. The extension returns sessionData as part of the Response.

You can store up to 4 KB of arbitrary data in the session. Any write operation that exceeds this limit will fail with a warning in the browser console. To avoid failures, store only necessary information in the session. For example, if you want to persist users' cart information in the session, instead of storing the complete cart object in the session, write cartId to the session and fetch the cart information using cartId from the API hub.

The example below shows an action saveCartIdInSession saving the cartId to the session object.

Implementing the action extensiontypescript
export default {
  actions: {
    saveCartIdInSession: async (
      request: Request,
      actionContext: ActionContext
    ): Response => {
      const sessionData = {
        cartId: '42',
        ...(request.sessionData || {}),
      };


      return {
        body: actualActionResult,
        statusCode: 200,
        sessionData,
      } as Response;
    },
  },
};

If you return sessionData from an action, you need to maintain all session information, even that which has not been updated. If you only return the sessionData with the keys added by the action, the existing session data will be lost because commercetools Frontend doesn't perform merge on the session but only stores the returned sessionData.

When multiple action calls write the session, the last action call to finish executing defines the outcome. Since this might lead to unexpected behavior in asynchronous and non-deterministic implementations, we recommended using the sdk.callAction() method. It handles sequential execution of multiple action calls automatically using a queue and provides a deterministic outcome.

Read the session

Any extension can read the sessionData since it's part of the Request object. An Action extension receives the Request directly as its input. Other extensions (data source and dynamic page handler) receive the Request as part of their corresponding context object. Direct session access in the frontend code is prohibited as the session might contain sensitive data, such as access tokens. Thus, the session JSON Web Token (JWT) is encrypted in the production environment.

To use parts of the session in a Frontend component, you can expose these parts selectively through a data source or action. For example, you can use the following data source extension to read the tracked cartId. The DataSourceContext carries the Request, which in turn carries sessionData (that might be empty if no session was written before).

Implementing the data source extensiontypescript
export default {
  'data-sources': {
    'example/get-cart-id': (
      configs: DataSourceConfiguration,
      context: DataSourceContext
    ): DataSourceResult => {
      console.log('Session data', context.request.sessionData?.cartId);
      return {
        dataSourcePayload: {
          cartId: context.request.sessionData?.cartId,
        },
      };
    },
  },
};

A Frontend component can use the exposed part of the sessionData after the data source is registered in the Studio, for example:

Implementing the React componenttypescript
import React from 'react';


type ShowCartIdTasticProps = {
  data: {
    cartId: string;
  };
};


const ShowCartIdTastic: React.FC<ShowCartIdTasticProps> = ({ data }) => {
  return !data?.cartId?.dataSource ? (
    <div>No cart Id available. Please continue to use our page!</div>
  ) : (
    <div>
      The active cart Id is <strong>{data?.cartId?.dataSource}</strong>
    </div>
  );
};


export default ShowCartIdTastic;
Frontend component schemajson
{
  "tasticType": "example/show-cart-id",
  "name": "Show active cart Id",
  "icon": "star",
  "description": "A frontend component showing the active cart Id",
  "schema": [
    {
      "name": "Data source",
      "fields": [
        {
          "label": "Active cart Id",
          "field": "cartId",
          "type": "dataSource",
          "dataSourceType": "example/get-cart-id"
        }
      ]
    }
  ]
}