diff --git a/docs/platforms/javascript/guides/react-router/index.mdx b/docs/platforms/javascript/guides/react-router/index.mdx index eaa9b230028fc2..a61b0d039b5d04 100644 --- a/docs/platforms/javascript/guides/react-router/index.mdx +++ b/docs/platforms/javascript/guides/react-router/index.mdx @@ -1,6 +1,6 @@ --- title: React Router Framework -description: Learn how to set up and configure Sentry in your React Router v7 application using the installation wizard, capture your first errors, and view them in Sentry. +description: Learn how to set up and configure Sentry in your React Router application (v7+) using the installation wizard, capture your first errors, and view them in Sentry. sdk: sentry.javascript.react-router categories: - javascript @@ -23,7 +23,7 @@ categories: -If you're using React Router in data or declarative mode, follow the instructions in our [React guide](/platforms/javascript/guides/react/features/react-router/v7). +If you're using React Router in data or declarative mode, follow the instructions in our React guide for [v7](/platforms/javascript/guides/react/features/react-router/v7) or [v8](/platforms/javascript/guides/react/features/react-router/v8). diff --git a/docs/platforms/javascript/guides/react-router/manual-setup.mdx b/docs/platforms/javascript/guides/react-router/manual-setup.mdx index 3ca87ccbd486a6..de8e7357d11549 100644 --- a/docs/platforms/javascript/guides/react-router/manual-setup.mdx +++ b/docs/platforms/javascript/guides/react-router/manual-setup.mdx @@ -1,7 +1,7 @@ --- title: "Manual Setup" sidebar_order: 1 -description: "Learn how to manually set up Sentry in your React Router v7 app and capture your first errors." +description: "Learn how to manually set up Sentry in your React Router app (v7+) and capture your first errors." --- diff --git a/docs/platforms/javascript/guides/react/features/react-router/index.mdx b/docs/platforms/javascript/guides/react/features/react-router/index.mdx index 4f80ebde0503be..8c179fb26e6bbf 100644 --- a/docs/platforms/javascript/guides/react/features/react-router/index.mdx +++ b/docs/platforms/javascript/guides/react/features/react-router/index.mdx @@ -15,7 +15,7 @@ The React Router integration is designed to work with Sentry Tracing. Please see The React Router instrumentation uses the React Router library to create `pageload/navigation` transactions to ensure you collect meaningful performance data about the health of your page loads and associated requests. -We support integrations for React Router 3, 4, 5, 6 and 7. +We support integrations for React Router 3, 4, 5, 6, 7, and 8. diff --git a/docs/platforms/javascript/guides/react/features/react-router/v6.mdx b/docs/platforms/javascript/guides/react/features/react-router/v6.mdx index e1dd54c74c3a14..386e9820b31804 100644 --- a/docs/platforms/javascript/guides/react/features/react-router/v6.mdx +++ b/docs/platforms/javascript/guides/react/features/react-router/v6.mdx @@ -4,6 +4,12 @@ description: "Learn how to instrument your React Router v6 application with Sent sidebar_order: 20 --- + + +Starting with SDK version `10.59.0`, Sentry provides version-agnostic APIs that replace the v6-specific ones used on this page. If you're on SDK `10.59.0` or later, we recommend using the [new APIs documented on the React Router v8 page](/platforms/javascript/guides/react/features/react-router/v8), which also work with React Router v6. The v6-specific APIs will be removed in the next major version. + + + Apply the following setup steps based on your routing method and create a [custom error boundary](#set-up-a-custom-error-boundary) to make sure Sentry automatically captures rendering errors: diff --git a/docs/platforms/javascript/guides/react/features/react-router/v7.mdx b/docs/platforms/javascript/guides/react/features/react-router/v7.mdx index 028eab1c0cf891..89934915779150 100644 --- a/docs/platforms/javascript/guides/react/features/react-router/v7.mdx +++ b/docs/platforms/javascript/guides/react/features/react-router/v7.mdx @@ -8,6 +8,13 @@ sidebar_order: 10 React Router v7 (framework mode) is currently in Beta, check out the docs [here](/platforms/javascript/guides/react-router/). + + + +Starting with SDK version `10.59.0`, Sentry provides version-agnostic APIs that replace the v7-specific ones used on this page. If you're on SDK `10.59.0` or later, we recommend using the [new APIs documented on the React Router v8 page](/platforms/javascript/guides/react/features/react-router/v8), which also work with React Router v7. The v7-specific APIs will be removed in the next major version. + + + Apply the following setup steps based on your routing method and create a [custom error boundary](#set-up-a-custom-error-boundary) to make sure Sentry automatically captures rendering errors: diff --git a/docs/platforms/javascript/guides/react/features/react-router/v8.mdx b/docs/platforms/javascript/guides/react/features/react-router/v8.mdx new file mode 100644 index 00000000000000..1d1acb3dc196aa --- /dev/null +++ b/docs/platforms/javascript/guides/react/features/react-router/v8.mdx @@ -0,0 +1,265 @@ +--- +title: React Router v8 (non-framework) +description: "Learn how to instrument your React Router v8 application with Sentry." +sidebar_order: 5 +--- + + + +Apply the following setup steps based on your routing method and create a +[custom error boundary](#set-up-a-custom-error-boundary) to make sure Sentry +automatically captures rendering errors: + + + +If you're using React Router v8 in framework mode, check out the [React Router Framework guide](/platforms/javascript/guides/react-router/). + + + + + +Starting with SDK version `10.59.0`, Sentry provides version-agnostic APIs that work with React Router v6, v7, and v8. If you're using React Router v6 or v7, you can also use these APIs instead of the version-specific ones documented on the [v6](/platforms/javascript/guides/react/features/react-router/v6) and [v7](/platforms/javascript/guides/react/features/react-router/v7) pages. + + + + + +## Usage with `createBrowserRouter` or `createMemoryRouter` (Data Mode) + +To instrument your React Router, use `Sentry.reactRouterBrowserTracingIntegration` within `Sentry.init` and provide the required React hooks and router functions. Then, wrap the router instance created by `createBrowserRouter` or `createMemoryRouter` with one of the following functions: + +- Use `Sentry.wrapCreateBrowserRouter` for [`createBrowserRouter`](https://reactrouter.com/api/router-components/BrowserRouter) and [`createHashRouter`](https://reactrouter.com/api/router-components/HashRouter) +- Use `Sentry.wrapCreateMemoryRouter` for [`createMemoryRouter`](https://reactrouter.com/api/router-components/MemoryRouter) + +```javascript {2-8, 15-21, 26-34} +import React from "react"; +import { + createBrowserRouter, + createRoutesFromChildren, + matchRoutes, + useLocation, + useNavigationType, +} from "react-router"; + +import * as Sentry from "@sentry/react"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + Sentry.reactRouterBrowserTracingIntegration({ + useEffect: React.useEffect, + useLocation, + useNavigationType, + createRoutesFromChildren, + matchRoutes, + }), + ], + tracesSampleRate: 1.0, +}); + +// Call this AFTER Sentry.init() +const sentryCreateBrowserRouter = + Sentry.wrapCreateBrowserRouter(createBrowserRouter); + +const router = sentryCreateBrowserRouter([ + // your routes... +]); +``` + +## Usage With `` Component (Declarative Mode) + +If you're using the `` component to define your routes, use `Sentry.reactRouterBrowserTracingIntegration` inside `Sentry.init` and provide the required React hooks and router functions. Then, wrap `` using `Sentry.wrapReactRouterRouting`. This creates a higher order component, which will enable Sentry to reach your router context. You can also use `Sentry.wrapReactRouterRouting` for routes inside `BrowserRouter`, `MemoryRouter`, and `HashRouter` components. + +```javascript {3-11, 18-24, 29, 33-35} +import React from "react"; +import ReactDOM from "react-dom/client"; +import { + Routes, + Route, + BrowserRouter, + useLocation, + useNavigationType, + createRoutesFromChildren, + matchRoutes, +} from "react-router"; + +import * as Sentry from "@sentry/react"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + Sentry.reactRouterBrowserTracingIntegration({ + useEffect: React.useEffect, + useLocation, + useNavigationType, + createRoutesFromChildren, + matchRoutes, + }), + ], + tracesSampleRate: 1.0, +}); + +const SentryRoutes = Sentry.wrapReactRouterRouting(Routes); + +ReactDOM.createRoot(document.getElementById("root")).render( + + + Home} /> + + +); +``` + +This wrapper is only needed at the top level of your app, unlike React Router v4/v5, which required wrapping every `` you wanted parametrized. + +## Usage With `useRoutes` Hook + +If you specify your route definitions as an object to the [`useRoutes` hook](https://reactrouter.com/api/hooks/useRoutes), use `Sentry.reactRouterBrowserTracingIntegration` inside `Sentry.init` and provide the required React hooks and router functions. Then, use `Sentry.wrapUseRoutes` to create a patched `useRoutes` hook that instruments your routes with Sentry. + + +Call `wrapUseRoutes` outside of a React component, as in the example below. We also recommend that you assign the wrapped hook to a variable starting with `use`, as per [React's documentation](https://react.dev/learn/reusing-logic-with-custom-hooks#hook-names-always-start-with-use). + + + +```javascript {2-10, 15-21, 26, 29-31} +import React from "react"; +import { + createRoutesFromChildren, + matchRoutes, + useLocation, + useNavigationType, + useRoutes, +} from "react-router"; + +import * as Sentry from "@sentry/react"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + Sentry.reactRouterBrowserTracingIntegration({ + useEffect: React.useEffect, + useLocation, + useNavigationType, + createRoutesFromChildren, + matchRoutes, + }), + ], + tracesSampleRate: 1.0, +}); + +const useSentryRoutes = Sentry.wrapUseRoutes(useRoutes); + +function App() { + return useSentryRoutes([ + // your routes... + ]); +} + +ReactDOM.createRoot(document.getElementById("root")).render( + + + +); +``` + +Now, Sentry should generate `pageload`/`navigation` transactions with parameterized transaction names (for example, `/teams/:teamid/user/:userid`), where applicable. This is only needed at the top level of your app, unlike React Router v4/v5, which required wrapping every `` you wanted parametrized. + +## Static Route Manifest + + + +When using [`patchRoutesOnNavigation`](https://reactrouter.com/api/data-routers/createBrowserRouter#optspatchroutesonnavigation) to dynamically load route definitions, the full route hierarchy isn't available to Sentry until each route is navigated to. This can cause transactions to receive incomplete or wildcard names (for example, `/users/*` instead of `/users/:userId`). + +To ensure accurate transaction names, you can provide a static list of route patterns via the `lazyRouteManifest` option. When provided, Sentry uses this manifest as the primary source for determining transaction names without needing to wait for route modules to load. + +Make sure to keep the `lazyRouteManifest` array in sync with your route definitions: if you add, remove, or change routes in your app, update this list accordingly. Any route that doesn't match a pattern in the manifest will fall back to the default behavior, which may result in incomplete transaction names until the route is visited. You can also include non-lazy routes in the manifest for convenience or consistency. + +To use `lazyRouteManifest`, you need to set `enableAsyncRouteHandlers: true` in your `reactRouterBrowserTracingIntegration` configuration: + +```javascript {20-27} +import React from "react"; +import { + createRoutesFromChildren, + matchRoutes, + useLocation, + useNavigationType, +} from "react-router"; + +import * as Sentry from "@sentry/react"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + Sentry.reactRouterBrowserTracingIntegration({ + useEffect: React.useEffect, + useLocation, + useNavigationType, + createRoutesFromChildren, + matchRoutes, + enableAsyncRouteHandlers: true, + lazyRouteManifest: [ + "/users", + "/users/:userId", + "/users/:userId/settings", + "/dashboard", + "/dashboard/analytics", + ], + }), + ], + tracesSampleRate: 1.0, +}); +``` + +## Set Up a Custom Error Boundary + +When using `react-router`, errors thrown inside route elements will only be re-thrown in **development mode** while using [`strict mode`](https://react.dev/reference/react/StrictMode).\ +In production, these errors won't surface unless captured manually. If you **don't** have a custom error boundary in place, `react-router` will create a default one that "swallows" all errors.\ +Hence, to capture these errors with Sentry in production, we strongly recommend to implement a custom error boundary. + +To send errors to Sentry while using a custom error boundary, use the `Sentry.captureException` method: + +```jsx {11, 28} +// router setup +const sentryCreateBrowserRouter = + Sentry.wrapCreateBrowserRouter(createBrowserRouter); +const router = sentryCreateBrowserRouter([ + { + path: "/", + element: , + children: [ + { + path: "", + element: , + errorElement: , + children: [ + // other routes ... + ], + }, + ], + }, +]); + +// error boundary +import { useRouteError } from "react-router"; +import * as Sentry from "@sentry/react"; + +export function YourCustomRootErrorBoundary() { + const error = useRouteError() as Error; + + React.useEffect(() => { + Sentry.captureException(error); + }, [error]); + + return ( +
+

Ouch!

+
+ ); +} + +``` + +## Next Steps + +- [Return to **Getting Started**](../../) +- [Return to the main integrations page](../)