/dd-instrument-rum

React integration

Read rum-core.md first. Use this integration only for plain React applications, not Next.js.

Prerequisites and packages

Require React 18 or 19. Stop before editing when the detected React major is unsupported.

Install together:

npm install --save @datadog/browser-rum @datadog/browser-rum-react

Keep both packages on the same exact version. Initialize at module scope in the browser entry before createRoot(...).render(...) or the legacy render call:

import { datadogRum } from '@datadog/browser-rum'
import { reactPlugin } from '@datadog/browser-rum-react'

datadogRum.init({
  // ...canonical fields from rum-core.md...
  plugins: [reactPlugin()],
})

Do not add router mode when the application does not use a supported router.

React Router

Support React Router v6, v7, and v8. Detect the installed major and the router APIs actually used. Initialize with:

plugins: [reactPlugin({ router: true })]

Replace only these imports when they are used: createBrowserRouter, createHashRouter, createMemoryRouter, useRoutes, and Routes. Keep unrelated router exports such as RouterProvider, Link, hooks, and route utilities on their original package.

Choose the matching Datadog entrypoint:

Do not use the version-agnostic react-router entrypoint for a known older major because it targets the latest supported router. Preserve whether the application imports its other APIs from react-router, react-router/dom, or react-router-dom.

TanStack Router

Require @tanstack/react-router >=1.64.0 and <2. Detect actual usage rather than enabling this path from dependency presence alone.

Use reactPlugin({ router: true }) and replace only the createRouter import:

- import { createRouter } from '@tanstack/react-router'
+ import { createRouter } from '@datadog/browser-rum-react/tanstack-router'

Keep RouterProvider, Link, route construction helpers, and all other TanStack exports imported from @tanstack/react-router.

If React Router and TanStack Router dependencies are both present, instrument only the router that constructs the active application router. Stop and ask rather than guessing when both are genuinely active entrypoints.

Error integration

Do not create a new error boundary or fallback UI solely for instrumentation.

• If the application already has a class error boundary, import addReactError and call it from the existing componentDidCatch(error, errorInfo) while preserving the handler's current behavior.
• If the application already uses React 19 createRoot error callbacks, call addReactError from those callbacks and preserve their logging/recovery logic.
• If the application already uses Datadog's ErrorBoundary or calls addReactError, do not add a second report path.
• Do not add onCaughtError when an existing boundary already reports the same caught error; that creates duplicates.

Core Browser RUM already captures uncaught browser errors. A project with no existing component-error surface remains valid with reactPlugin() and no invented UI.