Skip to content

hydrogen-react-router.mdx

Latest commit

 

History

History
382 lines (298 loc) · 11.6 KB

hydrogen-react-router.mdx

File metadata and controls

382 lines (298 loc) · 11.6 KB
title Hydrogen with React Router
description Learn how to instrument your Hydrogen app on Shopify Oxygen and capture your first errors and traces.

This guide applies to Hydrogen versions 2025.5.0 and later that use React Router 7 (framework mode). For older versions of Hydrogen that use Remix v2, see our Remix on Cloudflare guide.

Prerequisites

You need:

  • A Sentry account and project
  • Your Hydrogen application (v2025.5.0+), you want to host on Shopify Oxygen

Step 1: Install

Choose the features you want to configure, and this guide will show you how:

<OnboardingOptionButtons options={[ "error-monitoring", "performance", "session-replay", "user-feedback", "logs", ]} />

Install the Sentry SDK

Run the command for your preferred package manager to add the React Router and Cloudflare SDK:

npm install @sentry/react-router @sentry/cloudflare --save
yarn add @sentry/react-router @sentry/cloudflare
pnpm add @sentry/react-router @sentry/cloudflare

Step 2: Configure

Configure Client-side Sentry

Initialize Sentry in your entry.client.tsx file:

import { HydratedRouter } from "react-router/dom";
import * as Sentry from "@sentry/react-router/cloudflare";
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#sendDefaultPii
  sendDefaultPii: true,

  integrations: [
    // ___PRODUCT_OPTION_START___ performance
    // Registers and configures the Tracing integration,
    // which automatically instruments your application to monitor its
    // performance, including custom React Router routing instrumentation
    Sentry.reactRouterTracingIntegration(),
    // ___PRODUCT_OPTION_END___ performance
    // ___PRODUCT_OPTION_START___ session-replay
    // Registers the Replay integration,
    // which automatically captures Session Replays
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
    // ___PRODUCT_OPTION_START___ user-feedback
    Sentry.feedbackIntegration({
      // Additional SDK configuration goes in here, for example:
      colorScheme: "system",
    }),
    // ___PRODUCT_OPTION_END___ user-feedback
  ],
  // ___PRODUCT_OPTION_START___ logs

  // Enable logs to be sent to Sentry
  enableLogs: true,
  // ___PRODUCT_OPTION_END___ logs
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#traces-sample-rate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ session-replay

  // Capture Replay for 10% of all sessions,
  // plus 100% of sessions with an error
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/react-router/session-replay/configuration/#general-integration-configuration
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
});

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <HydratedRouter onError={Sentry.sentryOnError} />
    </StrictMode>
  );
});

The sentryOnError handler integrates with React Router's onError hook to automatically capture and report client-side errors to Sentry.

Configure Server-side Sentry

First, create an instrument.server.mjs file to initialize Sentry on the server:

import * as Sentry from "@sentry/react-router";

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#sendDefaultPii
  sendDefaultPii: true,
  // ___PRODUCT_OPTION_START___ logs

  // Enable logs to be sent to Sentry
  enableLogs: true,
  // ___PRODUCT_OPTION_END___ logs
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
});

Next, update your server.ts file to use the wrapRequestHandler method from @sentry/cloudflare:

import { wrapRequestHandler } from "@sentry/cloudflare";
// ...other imports

/**
 * Export a fetch handler in module format.
 */
export default {
  async fetch(
    request: Request,
    env: Env,
    executionContext: ExecutionContext
  ): Promise<Response> {
    return wrapRequestHandler(
      {
        options: {
          dsn: "___PUBLIC_DSN___",
          // ___PRODUCT_OPTION_START___ performance
          tracesSampleRate: 1.0,
          // ___PRODUCT_OPTION_END___ performance
          // ___PRODUCT_OPTION_START___ logs
          enableLogs: true,
          // ___PRODUCT_OPTION_END___ logs
          sendDefaultPii: true,
        },
        request: request as any,
        context: executionContext,
      },
      async () => {
        // Your existing Hydrogen server logic
        const handleRequest = createRequestHandler({
          // @ts-ignore
          build: await import("virtual:react-router/server-build"),
          mode: process.env.NODE_ENV,
          getLoadContext: (): AppLoadContext => ({
            // your load context
          }),
        });

        return handleRequest(request);
      }
    );
  },
};

Enable Distributed Tracing

Update your entry.server.tsx file to inject trace meta tags:

import "./instrument.server";
import { HandleErrorFunction, ServerRouter } from "react-router";
import type { EntryContext } from "@shopify/remix-oxygen";
import { renderToReadableStream } from "react-dom/server";
import * as Sentry from "@sentry/react-router/cloudflare";

async function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  reactRouterContext: EntryContext
) {
  const body = Sentry.injectTraceMetaTags(
    await renderToReadableStream(
      <ServerRouter context={reactRouterContext} url={request.url} />,
      {
        signal: request.signal,
      }
    )
  );

  responseHeaders.set("Content-Type", "text/html");

  return new Response(body, {
    headers: responseHeaders,
    status: responseStatusCode,
  });
}

export const handleError: HandleErrorFunction = (error, { request }) => {
  // React Router may abort some interrupted requests, don't log those
  if (!request.signal.aborted) {
    Sentry.captureException(error);
    console.error(error);
  }
};

export default Sentry.wrapSentryHandleRequest(handleRequest);

Step 3: Add Readable Stack Traces With Source Maps (Optional)

The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload your source maps to Sentry.

First, update vite.config.ts to include the sentryReactRouter plugin, making sure to pass both the Vite and Sentry configurations to it:

import { reactRouter } from "@react-router/dev/vite";
import { hydrogen } from "@shopify/hydrogen/vite";
import { oxygen } from "@shopify/mini-oxygen/vite";
import { defineConfig } from "vite";
import { sentryReactRouter } from "@sentry/react-router";

export default defineConfig((config) => ({
  plugins: [
    hydrogen(),
    oxygen(),
    reactRouter(),
    sentryReactRouter(
      {
        org: "___ORG_SLUG___",
        project: "___PROJECT_SLUG___",

        // An auth token is required for uploading source maps;
        // store it in an environment variable to keep it secure.
        authToken: process.env.SENTRY_AUTH_TOKEN,
      },
      config
    ),
    // ... other plugins
  ],
}));

Since the buildEnd hook will not be executed for Hydrogen, you need to manually upload source maps using the Sentry CLI instead:

# Inject debug IDs
sentry-cli sourcemaps inject /path/to/build/dir
# Upload sourcemaps
sentry-cli sourcemaps upload /path/to/build/dir

Step 4: Verify Your Setup

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

Issues

To verify that Sentry captures errors and creates issues in your Sentry project, throw an error in a loader:

import type { Route } from "./+types/sentry-test";

export async function loader() {
  throw new Error("My first Sentry error!");
}

export default function SentryTestPage() {
  return <div>Loading this page will throw an error</div>;
}
Open the `/sentry-test` route in your browser, and you should trigger an error. ### Tracing To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code: 
import * as Sentry from "@sentry/react-router/cloudflare";
import type { Route } from "./+types/sentry-test";

export async function loader() {
  return Sentry.startSpan(
    {
      op: "test",
      name: "My First Test Trace",
    },
    () => {
      throw new Error("My first Sentry error!");
    }
  );
}

export default function SentryTestPage() {
  return <div>Loading this page will throw an error</div>;
}

Open the /sentry-test route in your browser. You should start a trace and trigger an error.

View Captured Data in Sentry

Now, head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).

Next Steps

At this point, you should have integrated Sentry into your React Router Framework application and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: