diff --git a/docs/platforms/javascript/guides/react-router/index.mdx b/docs/platforms/javascript/guides/react-router/index.mdx index 100de8b26a163..d401261ab76f9 100644 --- a/docs/platforms/javascript/guides/react-router/index.mdx +++ b/docs/platforms/javascript/guides/react-router/index.mdx @@ -24,7 +24,7 @@ If you're using React Router in data or declarative mode, follow the instruction - + ## Install @@ -36,6 +36,18 @@ To install Sentry using the installation wizard, run the command on the right wi The wizard guides you through the setup process, asking you to enable additional (optional) Sentry features for your application beyond error monitoring. + + + +```bash +npx @sentry/wizard@latest -i reactRouter +``` + + + + + + This guide assumes that you enable all features and allow the wizard to create an example page and route. You can add or remove features at any time, but setting them up now will save you the effort of configuring them manually later. @@ -51,17 +63,6 @@ This guide assumes that you enable all features and allow the wizard to create a - - - -```bash -npx @sentry/wizard@latest -i reactRouter -``` - - - - - ## Configure If you prefer to configure Sentry manually, here are the configuration files the wizard would create: @@ -234,6 +235,8 @@ If you haven't tested your Sentry configuration yet, let's do it now. You can co 1. Open the example page `/sentry-example-page` in your browser. For most React Router applications, this will be at localhost. 2. Observe the example page with a button that triggers test errors. + + Clicking the button triggers an error that Sentry captures for you. The example also demonstrates how to test performance tracing. @@ -246,8 +249,6 @@ Don't forget to explore the example files' code in your project to understand wh Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). - - ## Next Steps @@ -270,4 +271,4 @@ Our next recommended steps for you are: - + diff --git a/docs/platforms/javascript/guides/react-router/manual-setup.mdx b/docs/platforms/javascript/guides/react-router/manual-setup.mdx index 3bb04159d3e95..36d201d67da7f 100644 --- a/docs/platforms/javascript/guides/react-router/manual-setup.mdx +++ b/docs/platforms/javascript/guides/react-router/manual-setup.mdx @@ -18,12 +18,39 @@ description: "Learn how to manually set up Sentry in your React Router v7 app an -## Step 1: Install + + +## Install + +Choose the features you want to configure, and this guide will show you how: + + + + ### Install the Sentry SDK + + + + Run the command for your preferred package manager to add the SDK package to your application: + + + ```bash {tabTitle:npm} @@ -55,37 +82,43 @@ pnpm add @sentry/react-router -## Step 2: Configure - -Choose the features you want to configure, and this guide will show you how: - - + + + - +## Configure ### Expose Entry Point Files + + + + Before configuring Sentry, you need to make React Router's entry files (`entry.client.tsx` and `entry.server.tsx`) visible in your project. Run this command to expose them: + + + ```bash npx react-router reveal ``` -### Configure Client-side Sentry + + + + +### Configure Client-Side Sentry + + + + -Initialize Sentry in your `entry.client.tsx` file: +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. + + + ```tsx {diff} {filename: entry.client.tsx} +import * as Sentry from "@sentry/react-router"; @@ -157,14 +190,18 @@ 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. + + + -### Configure Server-side Sentry +### Configure Server-Side Sentry - Automatic server-side instrumentation is currently only supported on: - - **Node 20:** Version \<20.19 - - **Node 22:** Version \<22.12 + +Automatic server-side instrumentation is currently only supported on: + +- **Node 20:** Version \<20.19 +- **Node 22:** Version \<22.12 If you're on a different version, you have two options: @@ -205,8 +242,15 @@ export const action = Sentry.wrapServerAction( + + + + First, create a file called `instrument.server.mjs` in the root of your project to initialize Sentry: + + + ```js {filename: instrument.server.mjs} import * as Sentry from "@sentry/react-router"; // ___PRODUCT_OPTION_START___ profiling @@ -246,8 +290,17 @@ Sentry.init({ }); ``` + + + + + + Next, replace the default `handleRequest` and `handleError` functions in your `entry.server.tsx` file with Sentry's wrapped versions: + + + ```tsx {diff} {filename: entry.server.tsx} +import * as Sentry from '@sentry/react-router'; import { createReadableStreamFromReadable } from '@react-router/node'; @@ -270,8 +323,13 @@ Next, replace the default `handleRequest` and `handleError` functions in your `e // ... rest of your server entry ``` + + + + - If you need to customize the logic of your `handleRequest` function, you'll need to use Sentry's helper functions (`getMetaTagTransformer` and `wrapSentryHandleRequest`) manually: + +If you need to customize the logic of your `handleRequest` function, you'll need to use Sentry's helper functions (`getMetaTagTransformer` and `wrapSentryHandleRequest`) manually: ```tsx {1-4, 44-45, 69-70} import { @@ -349,7 +407,8 @@ export default wrapSentryHandleRequest(handleRequest); - If you have custom logic in your `handleError` function, you'll need to capture errors manually: + +If you have custom logic in your `handleError` function, you'll need to capture errors manually: ```tsx {12} import { @@ -375,8 +434,15 @@ export function handleError( #### Load Instrumentation on Startup + + + + React Router runs in ESM mode, which means you need to load the Sentry instrumentation file before the application starts. Update your `package.json` scripts: + + + ```json {filename: package.json} "scripts": { "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router dev", @@ -384,12 +450,23 @@ React Router runs in ESM mode, which means you need to load the Sentry instrumen } ``` + + + + **Deploying to Vercel, Netlify, and similar platforms** + + + + If you're deploying to platforms where you can't set the `NODE_OPTIONS` flag, import the instrumentation file directly at the top of your `entry.server.tsx`: + + + ```tsx {diff} {filename: entry.server.tsx} +import './instrument.server'; import * as Sentry from '@sentry/react-router'; @@ -398,18 +475,29 @@ If you're deploying to platforms where you can't set the `NODE_OPTIONS` flag, im // ... rest of your imports ``` + + + + When you import the instrumentation file directly instead of using the `--import` flag, automatic instrumentation will be incomplete. You'll miss automatically captured spans and traces for some server-side operations. Only use this approach when the `NODE_OPTIONS` method isn't available. -## Step 3: Add Readable Stack Traces With Source Maps (Optional) +### 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: + + + ```typescript {filename: vite.config.ts} {diff} import { reactRouter } from '@react-router/dev/vite'; import { sentryReactRouter, type SentryReactRouterBuildOptions } from '@sentry/react-router'; @@ -432,18 +520,38 @@ export default defineConfig(config => { }); ``` + + + + + + To keep your auth token secure, always store it in an environment variable instead of directly in your files: + + + ```bash {filename:.env} SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ ``` - + + + + + + + + + Next, include the `sentryOnBuildEnd` hook in `react-router.config.ts`: + + + ```typescript {filename: react-router.config.ts} {diff} import type { Config } from "@react-router/dev/config"; import { sentryOnBuildEnd } from "@sentry/react-router"; @@ -458,17 +566,34 @@ export default { } satisfies Config; ``` -## Step 4: Avoid Ad Blockers With Tunneling (Optional) + + + + +### Avoid Ad Blockers With Tunneling (Optional) - + -## Step 5: Verify Your Setup +## 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: + + + + +To verify that Sentry captures errors and creates issues in your Sentry project, throw an error in a loader. + + + Then, open the route in your browser and you should trigger an error. + + + + + + ```tsx {filename: error.tsx} import type { Route } from "./+types/example-page"; @@ -482,15 +607,23 @@ export default function ExamplePage() { } ``` - - Open the 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: + + + + + +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. + +Then, open the route in your browser. You should start a trace and trigger an error. + + + ```tsx {filename: error.tsx} import * as Sentry from "@sentry/react-router"; @@ -513,13 +646,15 @@ export default function ExamplePage() { } ``` -Open the route in your browser. You should start a trace and trigger an error. + + + - + @@ -536,6 +671,7 @@ At this point, you should have integrated Sentry into your React Router Framewor Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +- Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup - Learn how to manually capture errors - Continue to customize your configuration - Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts @@ -546,3 +682,5 @@ Our next recommended steps for you are: - [Get support](https://sentry.zendesk.com/hc/en-us/) + +