Skip to main content



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 includes support for analytics that give you insight into how customers are interacting with a custom storefront. This guide describes how the analytics support that's built in to Hydrogen works

How it works

The following diagram describes how analytics data is processed on the server and client in Hydrogen:

Shows a diagram that describes how analytics data is processed on the server and client in Hydrogen

  1. On the server, the useServerAnalytics hook collects data in a single render request.

  2. On the client, the data is streamed as part of the Suspense component. This single render request waits for all queries to complete, outputs the collected data from the server-side, and triggers a PAGE_VIEW event.

  3. Events can be published to external endpoints from the client or server-side:

  • Client: The client can subscribe to events and publish them to external endpoints.
  • Server: Events are published to the /__event endpoint, a server analytics route. You can use server analytics connectors to publish the event to an external endpoint.

Default events

By default, Hydrogen publishes the following events to subscribers (ClientAnalytics.subscribe):

Event nameWhen the event is published
PAGE_VIEWA customer visits a storefront page
ADD_TO_CARTA customer adds an item to their cart
UPDATE_CARTA customer updates an item in their cart
REMOVE_FROM_CARTA customer removes an item from their cart
DISCOUNT_CODE_UPDATEDA discount code that a customer applies to a cart is updated
VIEWED_PRODUCTA customer views a product details page. This is set with publishEventsOnNavigate on product pages.
PERFORMANCEThe performance metrics for page loads in a Hydrogen storefront. This is available when you opt in to <PerformanceMetrics />.

Note: The event name constants are available in ClientAnalytics.eventNames.

Learn how to subscribe and unsubscribe to events, and learn how to configure custom events

Analytics sent from the server-side

Some information that isn't relevant to storefront customers, but might be helpful for the development team, is only available on the server. For example, server-side information includes detailed information about how many API calls a single page render makes, or how long each API call took.


The following table describes the request function parameters for ServerAnalyticsConnector:

requestUrlstringThe analytics request url.
requestHeaderHeadersThe analytics request headers object.
dataobject or textThe result from .json() or .text().
contentTypestringThe content type. Valid values: json or text.

Learn how to send analytics data from the server-side.

Performance metrics

Performance metrics provide insight into how fast pages are loading in your Hydrogen storefront. For example, you might want to gather the following metrics for full and sub page loads:

  • Time to First Byte (TTFB): The time between a browser requesting a page and receiving the first byte of information from the server
  • First Contentful Paint (FCP): The time it takes for a browser to render content on a page
  • Largest Contentful Paint (LCP): The time it takes to render and interact with the largest content element on the page
  • Duration: The total amount of time it takes for a page to finish streaming

Learn about displaying performance metrics.

Next steps