Shopify Hydrogen

Hydrogen storefronts render the HTML document from app/root.tsx, so the snippet goes in the <head> of that file's Layout component, and the tracker's host is added to the Content Security Policy that app/entry.server.tsx builds. This guide is for headless Hydrogen storefronts; for an Online Store theme, see the Shopify guide.

Get your tracking snippet

In your Rybbit dashboard, open Site Settings → Tracking Script and copy your snippet. It looks like this:

<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

YOUR_SITE_ID is the numeric ID of your site. If you self-host Rybbit, app.rybbit.io is the domain of your own instance.

Add the snippet to Shopify Hydrogen

Hydrogen ships with a nonce-based CSP, so a plain <script> tag without the nonce is blocked. Use Hydrogen's Script component, which adds the nonce for you.

Open app/root.tsx and add the tag inside <head> of the Layout component:

app/root.tsx

import { Analytics, getShopAnalytics, Script, useNonce } from "@shopify/hydrogen";

export function Layout({children}: {children?: React.ReactNode}) {
  const nonce = useNonce();

  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width,initial-scale=1" />
        <Meta />
        <Links />
        <Script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer />
      </head>
      <body>
        {children}
        <ScrollRestoration nonce={nonce} />
        <Scripts nonce={nonce} />
      </body>
    </html>
  );
}

Open app/entry.server.tsx and allow the tracker's host in the CSP. Values you pass for connectSrc are merged with Hydrogen's defaults, but scriptSrc has no default to merge with (it falls back to default-src), so list Shopify's CDN alongside Rybbit:

app/entry.server.tsx

const {nonce, header, NonceProvider} = createContentSecurityPolicy({
  shop: {
    checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
    storeDomain: context.env.PUBLIC_STORE_DOMAIN,
  },
  scriptSrc: ["'self'", "https://cdn.shopify.com", "https://app.rybbit.io"],
  connectSrc: ["https://app.rybbit.io"],
});

connect-src lets the tracker post events; script-src is needed because features such as session replay load a second script from the same host at runtime. If you self-host Rybbit, use your instance's domain.

Restart the dev server. Client-side navigation between routes is tracked automatically as pageviews. Projects created before Hydrogen moved to React Router import Meta, Links and Scripts from @remix-run/react; the edit is the same.

Verify installation

Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

If nothing shows up:

View the page source and search for script.js?siteId= to confirm the snippet is on the page.
Open the browser Network tab and check that script.js returns 200 and that POST requests go to /api/track.
Disable ad blockers, or set up a proxy so the script loads from your own domain.
See the script troubleshooting guide for other common causes.

Track custom events

Hydrogen's Analytics.Provider already publishes storefront events (product_viewed, product_added_to_cart, cart_updated and others), so subscribe to them once in a small component instead of instrumenting each route.

app/components/RybbitAnalytics.tsx

import { useAnalytics } from "@shopify/hydrogen";
import { useEffect } from "react";

export function RybbitAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register("Rybbit");

  useEffect(() => {
    subscribe("product_viewed", (data) => {
      const product = data.products[0];
      if (!product) return;
      window.rybbit?.event("view_item", {
        item_id: product.sku || product.variantId,
        item_name: product.title,
        item_variant: product.variantTitle,
        price: Number(product.price),
      });
    });
    subscribe("product_added_to_cart", (data) => {
      const line = data.currentLine;
      if (!line) return;
      window.rybbit?.event("add_to_cart", {
        item_id: line.merchandise.sku || line.merchandise.id,
        item_name: line.merchandise.product.title,
        price: Number(line.cost.totalAmount.amount),
        currency: line.cost.totalAmount.currencyCode,
        quantity: line.quantity,
      });
    });
    ready();
  }, []);

  return null;
}

Render <RybbitAnalytics /> inside <Analytics.Provider> in the App component of app/root.tsx. Declare window.rybbit with the type from Track events so TypeScript accepts the calls. Skip page_viewed: the tracker records route changes itself.

Checkout does not run in Hydrogen. Track purchases with the custom web pixel from the Shopify guide, which works for Hydrogen and Online Store checkouts alike.

Troubleshooting

Refused to load the script in the console: the CSP change in entry.server.tsx is missing or the dev server was not restarted. The nonce alone is not enough once session replay loads its second script.
POST /api/track blocked: connectSrc does not include the tracker's host. Self-hosted instances need their own domain here.
Early events dropped: on a cold load a subscription can fire before the deferred script runs. The optional chaining above skips those; wrap the calls in window.rybbit.onReady() if you need every one.

Next steps

Track custom events such as signups, purchases and button clicks.
Identify users to connect sessions to accounts.
Proxy the script through your own domain to bypass ad blockers.
Script attributes let you skip or mask URLs and tag events.