Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
37 changes: 16 additions & 21 deletions docs/platforms/javascript/guides/react/features/react-router/v6.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ sidebar_order: 20
---

<Alert level="info">
- React Router v6 support is included in the `@sentry/react` package since version `7`.
- React Router v6 support is included in the `@sentry/react` package since
version `7`.
</Alert>

Update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV6BrowserTracingIntegration` and provide the required React hooks and router functions:
Expand All @@ -17,20 +18,24 @@ Update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV6BrowserTr
<Alert level="warning">

To ensure proper routing instrumentation, initialize Sentry by calling `Sentry.init` **before**:

- Wrapping your `<Routes />` component
- Using `useRoutes`
- Using `createBrowserRouterV6`
- Using `wrapCreateBrowserRouterV6` or `wrapCreateMemoryRouterV6`

</Alert>

### Usage with `createBrowserRouter`
### Usage with `createBrowserRouter` or `createMemoryRouter`

<Alert level="info">
Available in `@sentry/react` version `7.21.0` and above.
</Alert>
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:

<Alert level="warning" title="Note">

If you choose to create your router instance with [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) from the `react-router-dom` package, you can use `Sentry.wrapCreateBrowserRouterV6` to wrap it with the instrumentation:
`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.

</Alert>

```javascript {2-8, 15-21, 26-33}
import React from "react";
Expand Down Expand Up @@ -66,18 +71,10 @@ const router = sentryCreateBrowserRouter([
]);
```

<Alert level="warning" title="Note">

You can instrument [`createMemoryRouter`](https://reactrouter.com/en/main/routers/create-memory-router) and [`createHashRouter`](https://reactrouter.com/en/main/routers/create-hash-router) using the `wrapCreateBrowserRouterV6` function.

</Alert>


### Usage With `<Routes />` Component

If you're using the `<Routes />` 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:


```javascript {3-11, 18-24, 29, 33-35}
import React from "react";
import ReactDOM from "react-dom";
Expand Down Expand Up @@ -123,7 +120,7 @@ This is only needed at the top level of your app, rather than how v4/v5 required
### Usage With `useRoutes` Hook

<Alert level="info">
Available in `@sentry/react` version `7.12.1` and above.
Available in `@sentry/react` version `7.12.1` and above.
</Alert>

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.
Expand All @@ -134,7 +131,6 @@ If you specify your route definitions as an object to the [`useRoutes` hook](htt

</Alert>


```javascript {2-10, 15-21, 26, 29-31}
import React from "react";
import {
Expand Down Expand Up @@ -179,13 +175,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 `<Route/>` you wanted parametrized.


### Custom Error Boundaries

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>
Note, that this only applies to render method and lifecycle errors since React doesn't need error boundaries to handle errors in event handlers.
Note, that this only applies to render method and lifecycle errors since React
doesn't need error boundaries to handle errors in event handlers.
</Note>

To send errors to Sentry while using a custom error boundary, use the `Sentry.captureException` method:
Expand All @@ -203,7 +199,7 @@ const router = sentryCreateBrowserRouter([
element: <Outlet />,
errorElement: <YourCustomRootErrorBoundary />,
children: [
// other routes ...
// other routes ...
],
},
],
Expand All @@ -230,7 +226,6 @@ export function YourCustomRootErrorBoundary() {

```


## Next Steps:

- [Return to **Getting Started**](../../)
Expand Down
37 changes: 18 additions & 19 deletions docs/platforms/javascript/guides/react/features/react-router/v7.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@ sidebar_order: 10
---

<Alert level="info">
- React Router v7 (library mode) support is included in the `@sentry/react` package since version `8.42.0`.
- React Router v7 (framework mode) is not yet supported.
- React Router v7 (library mode) support is included in the `@sentry/react`
package since version `8.42.0`. - React Router v7 (framework mode) is not yet
supported.
</Alert>

Update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV7BrowserTracingIntegration` and provide the required React hooks and router functions:
Expand All @@ -18,16 +19,24 @@ Update your `Sentry.browserTracingIntegration` to `Sentry.reactRouterV7BrowserTr
<Alert level="warning">

To ensure proper routing instrumentation, initialize Sentry by calling `Sentry.init` **before**:

- Wrapping your `<Routes />` component
- Using `useRoutes`
- Using `createBrowserRouterV7`
- Using `wrapCreateBrowserRouterV7` or `wrapCreateMemoryRouterV7`

</Alert>

### Usage with `createBrowserRouter`
### 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:

<Alert level="warning" title="Note">

`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.

If you choose to create your router instance with [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) from the `react-router` package, you can use `Sentry.wrapCreateBrowserRouterV7` to wrap it with the instrumentation:
You can instrument [`createHashRouter`](https://reactrouter.com/en/main/routers/create-hash-router) using the `wrapCreateBrowserRouterV7` function.

</Alert>

```javascript {2-8, 15-21, 26-33}
import React from "react";
Expand Down Expand Up @@ -63,18 +72,10 @@ const router = sentryCreateBrowserRouter([
]);
```

<Alert level="warning" title="Note">

You can instrument [`createMemoryRouter`](https://reactrouter.com/en/main/routers/create-memory-router) and [`createHashRouter`](https://reactrouter.com/en/main/routers/create-hash-router) using the `wrapCreateBrowserRouter` function.

</Alert>


### Usage With `<Routes />` Component

If you're using the `<Routes />` 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:


```javascript {3-11, 18-24, 29, 33-35}
import React from "react";
import ReactDOM from "react-dom";
Expand Down Expand Up @@ -127,7 +128,6 @@ If you specify your route definitions as an object to the [`useRoutes` hook](htt

</Alert>


```javascript {2-10, 15-21, 26, 29-31}
import React from "react";
import {
Expand Down Expand Up @@ -172,18 +172,17 @@ 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 `<Route/>` you wanted parametrized.


### Custom Error Boundaries

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>
Note, that this only applies to render method and lifecycle errors since React doesn't need error boundaries to handle errors in event handlers.
Note, that this only applies to render method and lifecycle errors since React
doesn't need error boundaries to handle errors in event handlers.
</Note>

To send errors to Sentry while using a custom error boundary, use the `Sentry.captureException` method:


```jsx {11, 28}
// router setup
const sentryCreateBrowserRouter = wrapCreateBrowserRouterV7(createBrowserRouter);
Expand All @@ -197,7 +196,7 @@ const router = sentryCreateBrowserRouter([
element: <Outlet />,
errorElement: <YourCustomRootErrorBoundary />,
children: [
// other routes ...
// other routes ...
],
},
],
Expand Down Expand Up @@ -227,4 +226,4 @@ export function YourCustomRootErrorBoundary() {
## Next Steps:

- [Return to **Getting Started**](../../)
- [Return to the main integrations page](../)
- [Return to the main integrations page](../)
Loading