Skip to main content

Manage sessions

tip

Hydrogen 2.0 is out now. These archival Hydrogen 1.0 docs are provided only to assist developers during their upgrade process. Please migrate as soon as possible.

Hydrogen's Demo Store template comes pre-configured with session support.

By default, session data is persisted within a cookie. You can adjust the session cookie configuration within your Hydrogen configuration file for an in-memory storage or file-based storage (NodeJS only), or build your own storage adapter.

Custom session storage​

If you want to persist session data in a custom way, then you can write your own session storage adapter. To do so, you need to implement a function that returns an object:

// customStorage.js

import {Cookie} from '@shopify/hydrogen';

export const CookieSessionStorage = function (name, options) {
  return function () {
    const cookie = new Cookie(name, options);
    return {
      async get(request) {
        const sid = cookie.getSessionId(request) || generateNewCookieId();
        const data = await customGetSessionData(sid);
        return data;
      },
      async set(request, value) {
        const sid = cookie.getSessionId(request) || generateNewCookieId();
        cookie.setSessionid(sid);
        await customPersistSessionData(sid, value);
        // When complete, return the serialized cookie
        return cookie.serialize();
      },
      async destroy(request) {
        await customDeleteTheSession();
        // When complete, return the destroyed cookie
        return cookie.destroy();
      },
    };
  };
};

Reading and updating session data​

In Hydrogen, you can use the useSession hook to read session data. You can update session data within API routes. API routes are passed a session object for interacting with the session. The session object has the following keys:

KeyDescription
getAn async function that resolves with the current session state.
setAn async function to modify a portion of the session state.
destroyAn async function to destroy the current session.

Example​

The following example shows an API route that's used to retrieve, set, and delete a countryCode within a session:

// my-api.server.js

export async function api(request, {session}) {
  let sessionData, jsonData;
  switch (request.method) {
    case 'GET':
      sessionData = await session.get();
      return {countryCode: sessionData.countryCode};
    case 'POST':
      jsonData = await request.json();
      await session.set('countryCode', jsonData.countryCode);
      return {countryCode: jsonData.countryCode};
    case 'DELETE':
      await session.destroy();
      return;
  }
  return new Response(null, {status: 400});
}

The following example shows a server component which reads data from the session:

// my-component.server.jsx

import {useSession} from '@shopify/hydrogen';

export async function MyComponent() {
  const {countryCode} = useSession();
}

Note: Session data is read-only within server components. To update or delete session data, use API functions.

Building custom session implementations​

Hydrogen provides a Cookie component for building your own custom cookie and session implementations. All Hydrogen session storage mechanisms use the same configuration options as Cookie.

Next steps​