Skip to content

docs(js): Use split layout in Astro & Hydrogen with React Router quick start guides #17315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
inventarSarah merged 2 commits into from
Apr 14, 2026
+337 −58
Merged

docs(js): Use split layout in Astro & Hydrogen with React Router quick start guides #17315

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
541806d
astro quick start split layout
inventarSarah Apr 13, 2026
24b0384
Hydrogen with react router quick start guide split layout
inventarSarah Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions docs/platforms/javascript/guides/astro/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,18 @@ You need:
- If you're using Astro's Netlify adapter (`@astrojs/netlify`), you need version `5.0.0` or above

<Alert level="warning" title="What runtime do you use?">
This SDK currently only works on Node runtimes, such as Node adapter or Vercel
with Lambda functions. If you use Cloudflare Workers or Cloudflare Pages, refer to our [Astro on
Cloudflare guide](/platforms/javascript/guides/cloudflare/frameworks/astro/).
Other non-Node runtimes, like Vercel's Edge runtime, are currently **not
supported**.

This SDK currently only works on Node runtimes, such as Node adapter or Vercel
with Lambda functions. If you use Cloudflare Workers or Cloudflare Pages, refer to our [Astro on
Cloudflare guide](/platforms/javascript/guides/cloudflare/frameworks/astro/).
Other non-Node runtimes, like Vercel's Edge runtime, are currently **not
supported**.

</Alert>

## Step 1: Install
<StepConnector selector="h2" showNumbers={true}>

## Install

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

Expand All @@ -44,3 +48,5 @@ Choose the features you want to configure, and this guide will show you how:
<Include name="quick-start-features-expandable" />

<PlatformContent includePath="getting-started-complete" />

</StepConnector>
41 changes: 40 additions & 1 deletion docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,18 @@ Sentry integration and full feature support.

<Expandable level="info" title="Using Astro on Cloudflare Pages?">

<SplitLayout>

For Cloudflare Pages, you need to manually set up the `@sentry/cloudflare` SDK using the Pages middleware.

<SplitSection>
<SplitSectionText>

1. Install both SDKs:

</SplitSectionText>
<SplitSectionCode>

```bash {tabTitle:npm}
npm install @sentry/astro @sentry/cloudflare
```
Expand All @@ -35,8 +43,17 @@ yarn add @sentry/astro @sentry/cloudflare
pnpm add @sentry/astro @sentry/cloudflare
```

</SplitSectionCode>
</SplitSection>

<SplitSection>
<SplitSectionText>

2. Add the Sentry Astro integration to your `astro.config.mjs`:

</SplitSectionText>
<SplitSectionCode>

```javascript {filename:astro.config.mjs}
import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
Expand All @@ -48,8 +65,17 @@ export default defineConfig({
});
```

</SplitSectionCode>
</SplitSection>

<SplitSection>
<SplitSectionText>

3. <Include name="cloudflare-pages-middleware-intro.mdx" />

</SplitSectionText>
<SplitSectionCode>

```javascript {filename:functions/_middleware.js}
import * as Sentry from "@sentry/cloudflare";

Expand All @@ -64,11 +90,22 @@ export const onRequest = [
];
```

</SplitSectionCode>
</SplitSection>

<SplitSection>
<SplitSectionText>

4. Make sure to [configure Cloudflare for Sentry](/platforms/javascript/guides/cloudflare/#wrangler-configuration).

</SplitSectionText>
</SplitSection>
</SplitLayout>
</Expandable>

## Step 1: Install
<StepConnector selector="h2" showNumbers={true}>

## Install

<OnboardingOptionButtons
options={[
Expand All @@ -86,3 +123,5 @@ export const onRequest = [
includePath="getting-started-complete"
platform="javascript.astro"
/>

</StepConnector>
133 changes: 115 additions & 18 deletions docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ You need:
- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/)
- Your Hydrogen application (v2025.5.0+), you want to host on Shopify Oxygen

## Step 1: Install
<StepConnector selector="h2" showNumbers={true}>

## Install

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

Expand All @@ -34,8 +36,15 @@ Choose the features you want to configure, and this guide will show you how:

### Install the Sentry SDK

<SplitLayout>
<SplitSection>
<SplitSectionText>

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

</SplitSectionText>
<SplitSectionCode>

```bash {tabTitle:npm}
npm install @sentry/react-router @sentry/cloudflare --save
```
Expand All @@ -48,11 +57,24 @@ yarn add @sentry/react-router @sentry/cloudflare
pnpm add @sentry/react-router @sentry/cloudflare
```

## Step 2: Configure
</SplitSectionCode>
</SplitSection>
</SplitLayout>

## Configure

### Configure Client-side Sentry

Initialize Sentry in your `entry.client.tsx` file:
<SplitLayout>
<SplitSection>
<SplitSectionText>

Initialize Sentry in your `entry.client.tsx` file.

The `sentryOnError` handler integrates with React Router's [`onError` hook](https://reactrouter.com/how-to/error-reporting) to automatically capture and report client-side errors to Sentry.

</SplitSectionText>
<SplitSectionCode>

```tsx {filename: app/entry.client.tsx}
import { HydratedRouter } from "react-router/dom";
Expand Down Expand Up @@ -121,12 +143,21 @@ startTransition(() => {
});
```

The `sentryOnError` handler integrates with React Router's [`onError` hook](https://reactrouter.com/how-to/error-reporting) to automatically capture and report client-side errors to Sentry.
</SplitSectionCode>
</SplitSection>
</SplitLayout>

### Configure Server-side Sentry

<SplitLayout>
<SplitSection>
<SplitSectionText>

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

</SplitSectionText>
<SplitSectionCode>

```js {filename:instrument.server.mjs}
import * as Sentry from "@sentry/react-router";

Expand All @@ -153,8 +184,17 @@ Sentry.init({
});
```

</SplitSectionCode>
</SplitSection>

<SplitSection>
<SplitSectionText>

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

</SplitSectionText>
<SplitSectionCode>

```ts {filename:server.ts}
import { wrapRequestHandler } from "@sentry/cloudflare";
// ...other imports
Expand Down Expand Up @@ -201,12 +241,23 @@ export default {
};
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

<OnboardingOption optionId="performance">

### Enable Distributed Tracing

<SplitLayout>
<SplitSection>
<SplitSectionText>

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

</SplitSectionText>
<SplitSectionCode>

```tsx {filename:app/entry.server.tsx}
import "./instrument.server";
import { HandleErrorFunction, ServerRouter } from "react-router";
Expand Down Expand Up @@ -248,13 +299,24 @@ export const handleError: HandleErrorFunction = (error, { request }) => {
export default Sentry.wrapSentryHandleRequest(handleRequest);
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

</OnboardingOption>

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

<SplitLayout>
<SplitSection>
<SplitSectionText>

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:
First, update `vite.config.ts` to include the `sentryReactRouter` plugin, making sure to pass both the Vite and Sentry configurations to it.

</SplitSectionText>
<SplitSectionCode>

```ts {filename:vite.config.ts}
import { reactRouter } from "@react-router/dev/vite";
Expand Down Expand Up @@ -284,7 +346,16 @@ export default defineConfig((config) => ({
}));
```

Since the `buildEnd` hook will not be executed for Hydrogen, you need to manually upload source maps using the [Sentry CLI](/cli/) instead:
</SplitSectionCode>
</SplitSection>

<SplitSection>
<SplitSectionText>

Since the `buildEnd` hook will not be executed for Hydrogen, you need to manually upload source maps using the [Sentry CLI](/cli/) instead.

</SplitSectionText>
<SplitSectionCode>

```bash
# Inject debug IDs
Expand All @@ -293,13 +364,28 @@ sentry-cli sourcemaps inject /path/to/build/dir
sentry-cli sourcemaps upload /path/to/build/dir
```

## Step 4: Verify Your Setup
</SplitSectionCode>
</SplitSection>
</SplitLayout>

## 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:
<SplitLayout>
<SplitSection>
<SplitSectionText>

<PlatformContent includePath="getting-started-browser-sandbox-warning" />

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

Next, open the `/sentry-test` route in your browser, and you should trigger an error.

</SplitSectionText>
<SplitSectionCode>

```tsx {filename: app/routes/sentry-test.tsx}
import type { Route } from "./+types/sentry-test";
Expand All @@ -313,16 +399,23 @@ export default function SentryTestPage() {
}
```

<OnboardingOption optionId="performance" hideForThisOption>
Open the `/sentry-test` route in your browser, and you should trigger an
error.
</OnboardingOption>

<PlatformContent includePath="getting-started-browser-sandbox-warning" />
</SplitSectionCode>
</SplitSection>
</SplitLayout>

<OnboardingOption optionId="performance">
### 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:

<SplitLayout>
<SplitSection>
<SplitSectionText>

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.

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

</SplitSectionText>
<SplitSectionCode>

```tsx {filename: app/routes/sentry-test.tsx}
import * as Sentry from "@sentry/react-router/cloudflare";
Expand All @@ -345,13 +438,15 @@ export default function SentryTestPage() {
}
```

Open the `/sentry-test` route in your browser. You should start a trace and trigger an error.
</SplitSectionCode>
</SplitSection>
</SplitLayout>

</OnboardingOption>

<OnboardingOption optionId="logs">

<Include name="logs/javascript-quick-start-verify-logs" />
<Include name="logs/javascript-quick-start-verify-logs-splitlayout" />

</OnboardingOption>

Expand Down Expand Up @@ -380,3 +475,5 @@ Our next recommended steps for you are:
- [Get support](https://sentry.zendesk.com/hc/en-us/)

</Expandable>

</StepConnector>
Loading
Loading