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 f12af4ecd0a46..353d2a5383ec5 100644 --- a/docs/platforms/javascript/guides/react/features/react-router/v6.mdx +++ b/docs/platforms/javascript/guides/react/features/react-router/v6.mdx @@ -1,41 +1,19 @@ --- title: React Router v6 -description: "Learn about Sentry's React Router v6 integration." +description: "Learn how to instrument your React Router v6 application with Sentry." sidebar_order: 20 --- - - - React Router v6 support is included in the `@sentry/react` package since - version `7`. - - -Update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV6BrowserTracingIntegration` and provide the required React hooks and router functions: - - - `useEffect` hook from `react` - - `useLocation` and `useNavigationType` hooks from `react-router-dom` or `react-router` - - `createRoutesFromChildren` and `matchRoutes` functions from `react-router-dom` or `react-router` - - - -To ensure proper routing instrumentation, initialize Sentry by calling `Sentry.init` **before**: - -- Wrapping your `` component -- Using `useRoutes` -- Using `wrapCreateBrowserRouterV6` or `wrapCreateMemoryRouterV6` - - +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: -### Usage with `createBrowserRouter` or `createMemoryRouter` + -If you choose to create your router instance with [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) or [`createMemoryRouter`](https://reactrouter.com/en/main/routers/create-memory-router), you can use `Sentry.wrapCreateBrowserRouterV6` or `Sentry.wrapCreateMemoryRouterV6` to wrap it with the instrumentation: +## Usage with `createBrowserRouter` or `createMemoryRouter` - +To instrument your React Router, update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV6BrowserTracingIntegration` 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: -`wrapCreateMemoryRouterV6` was introduced in SDK version 8.50.0. Prior to that version, we suggested using `wrapCreateBrowserRouterV6` with `createMemoryRouter`. If you are currently using `wrapCreateBrowserRouterV6` to wrap `createMemoryRouter`, it is recommended that you use `wrapCreateMemoryRouterV6` instead. - -You can instrument [`createHashRouter`](https://reactrouter.com/en/main/routers/create-hash-router) using the `wrapCreateBrowserRouterV6` function. - - +- Use `Sentry.wrapCreateBrowserRouterV6` for [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) and [`createHashRouter`](https://reactrouter.com/en/main/routers/create-hash-router) +- Use `Sentry.wrapCreateMemoryRouterV6` for [`createMemoryRouter`](https://reactrouter.com/en/main/routers/create-memory-router) (introduced in SDK version `8.50.0`) ```javascript {2-8, 15-21, 26-33} import React from "react"; @@ -71,9 +49,9 @@ const router = sentryCreateBrowserRouter([ ]); ``` -### Usage With `` Component +## Usage With `` Component -If you're using the `` component to define your routes, wrap [`Routes`](https://reactrouter.com/en/main/components/routes) using `Sentry.withSentryReactRouterV6Routing`. This creates a higher order component, which will enable Sentry to reach your router context. You can also use `Sentry.withSentryReactRouterV6Routing` for `Routes` inside `BrowserRouter`. `MemoryRouter`, and `HashRouter` components: +If you're using the `` component to define your routes, update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV6BrowserTracingIntegration` inside `Sentry.init` and provide the required React hooks and router functions. Then, wrap `` using `Sentry.withSentryReactRouterV6Routing`. This creates a higher order component, which will enable Sentry to reach your router context. You can also use `Sentry.withSentryReactRouterV6Routing` for routes inside `BrowserRouter`, `MemoryRouter`, and `HashRouter` components. ```javascript {3-11, 18-24, 29, 33-35} import React from "react"; @@ -115,19 +93,16 @@ ReactDOM.render( ); ``` -This is only needed at the top level of your app, rather than how v4/v5 required wrapping every `` you wanted parametrized. +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 +## Usage With `useRoutes` Hook - - Available in `@sentry/react` version `7.12.1` and above. - +_Available in `@sentry/react` version `7.12.1` and above._ -If you specify your route definitions as an object to the [`useRoutes` hook](https://reactrouter.com/en/main/hooks/use-routes), use `Sentry.wrapUseRoutesV6` to create a patched `useRoutes` hook that instruments your routes with Sentry. +If you specify your route definitions as an object to the [`useRoutes` hook](https://reactrouter.com/en/main/hooks/use-routes), update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV6BrowserTracingIntegration` inside `Sentry.init` and provide the required React hooks and router functions. Then, use `Sentry.wrapUseRoutesV6` to create a patched `useRoutes` hook that instruments your routes with Sentry. - - -`wrapUseRoutesV6` should be called outside of a React component, as in the example below. It's also recommended that you assign the wrapped hook to a variable name starting with `use`, as per the [React documentation](https://reactjs.org/docs/hooks-custom.html#extracting-a-custom-hook). + +Call `wrapUseRoutesV6` 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). @@ -173,16 +148,13 @@ ReactDOM.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, rather than how v4/v5 required wrapping every `` you wanted parametrized. - -### Custom Error Boundaries +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. -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 be surfaced unless manually captured. If you **don't** have a custom error boundary in place, `react-router` will create a default one that "swallows" all errors. +## Set Up a Custom Error Boundary - - Note, that this only applies to render method and lifecycle errors since React - doesn't need error boundaries to handle errors in event handlers. - +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: @@ -226,7 +198,7 @@ export function YourCustomRootErrorBoundary() { ``` -## Next Steps: +## Next Steps - [Return to **Getting Started**](../../) - [Return to the main integrations page](../) 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 f5c12d11d2710..c02bac2e29da4 100644 --- a/docs/platforms/javascript/guides/react/features/react-router/v7.mdx +++ b/docs/platforms/javascript/guides/react/features/react-router/v7.mdx @@ -1,46 +1,25 @@ --- title: React Router v7 (library mode) -description: "Learn about Sentry's React Router v7 integration." +description: "Learn how to instrument your React Router v7 application with Sentry." sidebar_order: 10 --- - - - - React Router v7 (framework mode) is currently in experimental Alpha, check out the docs [here](/platforms/javascript/guides/react-router/). - - - - React Router v7 (library mode) support is included in the `@sentry/react` - package since version `8.42.0`. - - -Update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV7BrowserTracingIntegration` and provide the required React hooks and router functions: - - - `useEffect` hook from `react` - - `useLocation` and `useNavigationType` hooks from `react-router` - - `createRoutesFromChildren` and `matchRoutes` functions from `react-router` - - - -To ensure proper routing instrumentation, initialize Sentry by calling `Sentry.init` **before**: - -- Wrapping your `` component -- Using `useRoutes` -- Using `wrapCreateBrowserRouterV7` or `wrapCreateMemoryRouterV7` - + + React Router v7 (framework mode) is currently in experimental Alpha, check out + the docs [here](/platforms/javascript/guides/react-router/). +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: -### Usage with `createBrowserRouter` or `createMemoryRouter` - -If you choose to create your router instance with [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) or [`createMemoryRouter`](https://reactrouter.com/en/main/routers/create-memory-router), you can use `Sentry.wrapCreateBrowserRouterV7` or `Sentry.wrapCreateMemoryRouterV7` to wrap it with the instrumentation: - - + -`wrapCreateMemoryRouterV7` was introduced in SDK version 8.50.0. Prior to that version, we suggested using `wrapCreateBrowserRouterV7` with `createMemoryRouter`. If you are currently using `wrapCreateBrowserRouterV7` to wrap `createMemoryRouter`, it is recommended that you use `wrapCreateMemoryRouterV7` instead. +## Usage with `createBrowserRouter` or `createMemoryRouter` -You can instrument [`createHashRouter`](https://reactrouter.com/en/main/routers/create-hash-router) using the `wrapCreateBrowserRouterV7` function. +To instrument your React Router, update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV7BrowserTracingIntegration` 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.wrapCreateBrowserRouterV7` for [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) and [`createHashRouter`](https://reactrouter.com/en/main/routers/create-hash-router) +- Use `Sentry.wrapCreateMemoryRouterV7` for [`createMemoryRouter`](https://reactrouter.com/en/main/routers/create-memory-router) (introduced in SDK version `8.50.0`) ```javascript {2-8, 15-21, 26-33} import React from "react"; @@ -76,9 +55,9 @@ const router = sentryCreateBrowserRouter([ ]); ``` -### Usage With `` Component +## Usage With `` Component -If you're using the `` component to define your routes, wrap [`Routes`](https://reactrouter.com/en/main/components/routes) using `Sentry.withSentryReactRouterV7Routing`. This creates a higher order component, which will enable Sentry to reach your router context. You can also use `Sentry.withSentryReactRouterV7Routing` for `Routes` inside `BrowserRouter`. `MemoryRouter`, and `HashRouter` components: +If you're using the `` component to define your routes, update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV7BrowserTracingIntegration` inside `Sentry.init` and provide the required React hooks and router functions. Then, wrap `` using `Sentry.withSentryReactRouterV7Routing`. This creates a higher order component, which will enable Sentry to reach your router context. You can also use `Sentry.withSentryReactRouterV7Routing` for routes inside `BrowserRouter`, `MemoryRouter`, and `HashRouter` components. ```javascript {3-11, 18-24, 29, 33-35} import React from "react"; @@ -120,15 +99,14 @@ ReactDOM.render( ); ``` -This is only needed at the top level of your app, rather than how v4/v5 required wrapping every `` you wanted parametrized. - -### Usage With `useRoutes` Hook +This wrapper is only needed at the top level of your app, unlike React Router v4/v5, which required wrapping every `` you wanted parametrized. -If you specify your route definitions as an object to the [`useRoutes` hook](https://reactrouter.com/en/main/hooks/use-routes), use `Sentry.wrapUseRoutesV7` to create a patched `useRoutes` hook that instruments your routes with Sentry. +## Usage With `useRoutes` Hook - +If you specify your route definitions as an object to the [`useRoutes` hook](https://reactrouter.com/en/main/hooks/use-routes), update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV7BrowserTracingIntegration` inside `Sentry.init` and provide the required React hooks and router functions. Then, use `Sentry.wrapUseRoutesV7` to create a patched `useRoutes` hook that instruments your routes with Sentry. -`wrapUseRoutesV7` should be called outside of a React component, as in the example below. It's also recommended that you assign the wrapped hook to a variable name starting with `use`, as per the [React documentation](https://reactjs.org/docs/hooks-custom.html#extracting-a-custom-hook). + +Call `wrapUseRoutesV7` 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). @@ -174,16 +152,13 @@ ReactDOM.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, rather than how v4/v5 required wrapping every `` you wanted parametrized. +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. -### Custom Error Boundaries +## 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 be surfaced unless manually captured. If you **don't** have a custom error boundary in place, `react-router` will create a default one that "swallows" all errors. - - - Note, that this only applies to render method and lifecycle errors since React - doesn't need error boundaries to handle errors in event handlers. - +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: @@ -227,7 +202,7 @@ export function YourCustomRootErrorBoundary() { ``` -## Next Steps: +## Next Steps - [Return to **Getting Started**](../../) - [Return to the main integrations page](../)