[NextJS] Nextjs app router integration (AI optimistic) by lierniel · Pull Request #4234 · DataDog/browser-sdk

lierniel · 2026-02-25T01:51:35Z

✨ Add Next.js App Router integration for `@datadog/browser-rum-react`

Motivation

Next.js App Router is a widely adopted routing paradigm (Next.js 13.4+), but RUM view tracking requires manual instrumentation today. This integration provides a <DatadogRumProvider> component that automatically tracks client-side navigations as RUM views with parameterized route names (e.g., /users/:id), following the same sub-package pattern as the existing React Router integrations.

Changes

Plugin configuration (packages/rum-react/src/domain/reactPlugin.ts):

Add nextAppRouter?: boolean option to ReactPluginConfiguration
Automatically set trackViewsManually = true when nextAppRouter is enabled
Warn when both router and nextAppRouter are enabled simultaneously
Report nextAppRouter in configuration telemetry

View name computation (packages/rum-react/src/domain/nextjs/computeNextViewName.ts):

Segment-aware param replacement: reconstructs parameterized route patterns from pathname + params (e.g., /users/123 + { id: '123' } → /users/:id)
Handles catch-all segments ([...slug] → /:slug), multi-occurrence params, and edge cases (empty/undefined values)
Array params processed before string params to avoid partial replacements

Provider component (packages/rum-react/src/domain/nextjs/datadogRumProvider.tsx):

Client-side DatadogRumProvider component that reads usePathname() / useParams() from next/navigation
Uses ref-based deduplication to prevent duplicate views on re-renders
Defers view start via onRumInit subscriber pattern (safe for any init order)
Deduplicates by computed view name (not raw pathname), so /users/123 → /users/456 does not start a new view if both resolve to /users/:id

Sub-package entry point:

packages/rum-react/nextjs/package.json — shim pointing to compiled artifacts (same pattern as react-router-v6/, react-router-v7/)
packages/rum-react/src/entries/nextjs.ts — entry point exporting DatadogRumProvider

Sample test app (test/apps/nextjs-app/):

Simulates Next.js routing via mockNextNavigation.tsx (mock usePathname, useParams, useNavigate backed by React context)
Routes: home (/), dynamic param (/user/:id), tracked component (/tracked), error boundary (/error)
Uses DatadogRumProvider, ErrorBoundary, UNSTABLE_ReactComponentTracker from the SDK
Registered in scripts/build/build-test-apps.ts and test/e2e/lib/framework/sdkBuilds.ts

E2E tests (test/e2e/scenario/reactPlugin.scenario.ts):

View name tracking: navigate to /user/42, verify last view name is /user/:id
Component render vital: navigate to tracked page, verify TrackedPage vital with duration
Error boundary: trigger error, verify error event with framework: 'react' and component stack

Test instructions

Run unit tests: yarn test:unit --spec packages/rum-react/src/domain/nextjs/computeNextViewName.spec.ts and the other spec files in packages/rum-react/src/domain/nextjs/
Run plugin tests: yarn test:unit --spec packages/rum-react/src/domain/reactPlugin.spec.ts
Build test apps: yarn build:apps
Run E2E tests: yarn test:e2e -g "Next.js App Router"
Verify typecheck: yarn typecheck

Checklist

Tested locally
Tested on staging
Added unit tests for this change.
Added e2e/integration tests for this change.
Updated documentation and/or relevant AGENTS.md file

github-actions · 2026-02-25T01:51:48Z

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

I have read the CLA Document and I hereby sign the CLA

_{You can retrigger this bot by commenting recheck in this Pull Request.}_{Posted by the CLA Assistant Lite bot.}

datadog-official · 2026-02-25T01:54:20Z

⚠️ Tests

✨ Fix all issues with BitsAI or with Cursor

⚠️ Warnings

🧪 33 Tests failed

DatadogRumProvider does not start a new view on re-render with same pathname from Chrome 63.0.3239.84 (Windows 10) (Datadog) (Fix with Cursor)

Error: Should not already be working.
    at performWorkOnRoot (webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:16424:15 <- /tmp/_karma_webpack_197022/commons.js:28712:87)
    at performWorkOnRootViaSchedulerTask (webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:18957:7 <- /tmp/_karma_webpack_197022/commons.js:29863:9)
    at flushActQueue (webpack:///node_modules/react/cjs/react.development.js:590:34 <- /tmp/_karma_webpack_197022/commons.js:37742:44)
    at exports.act (webpack:///node_modules/react/cjs/react.development.js:884:10 <- /tmp/_karma_webpack_197022/commons.js:37928:37)
    at appendComponent (webpack:///packages/rum-react/test/appendComponent.ts:13:6 <- /tmp/_karma_webpack_197022/commons.js:92365:47)
    at UserContext.it (webpack:///packages/rum-react/src/domain/nextjs/datadogRumProvider.spec.tsx:59:20 <- /tmp/_karma_webpack_197022/commons.js:90920:79)
    at <Jasmine>

DatadogRumProvider does not start a new view when navigating to a different instance of the same route from Chrome 63.0.3239.84 (Windows 10) (Datadog) (Fix with Cursor)

Error: Should not already be working.
    at performWorkOnRoot (webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:16424:15 <- /tmp/_karma_webpack_197022/commons.js:28712:87)
    at performWorkOnRootViaSchedulerTask (webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:18957:7 <- /tmp/_karma_webpack_197022/commons.js:29863:9)
    at flushActQueue (webpack:///node_modules/react/cjs/react.development.js:590:34 <- /tmp/_karma_webpack_197022/commons.js:37742:44)
    at exports.act (webpack:///node_modules/react/cjs/react.development.js:884:10 <- /tmp/_karma_webpack_197022/commons.js:37928:37)
    at appendComponent (webpack:///packages/rum-react/test/appendComponent.ts:13:6 <- /tmp/_karma_webpack_197022/commons.js:92365:47)
    at UserContext.it (webpack:///packages/rum-react/src/domain/nextjs/datadogRumProvider.spec.tsx:107:20 <- /tmp/_karma_webpack_197022/commons.js:90955:79)
    at <Jasmine>

DatadogRumProvider renders children without wrapper DOM elements from Chrome 63.0.3239.84 (Windows 10) (Datadog) (Fix with Cursor)

SyntaxError: Failed to execute 'measure' on 'Performance': The mark '[object Object]' does not exist.
error properties: Object({ INDEX_SIZE_ERR: 1, DOMSTRING_SIZE_ERR: 2, HIERARCHY_REQUEST_ERR: 3, WRONG_DOCUMENT_ERR: 4, INVALID_CHARACTER_ERR: 5, NO_DATA_ALLOWED_ERR: 6, NO_MODIFICATION_ALLOWED_ERR: 7, NOT_FOUND_ERR: 8, NOT_SUPPORTED_ERR: 9, INUSE_ATTRIBUTE_ERR: 10, INVALID_STATE_ERR: 11, SYNTAX_ERR: 12, INVALID_MODIFICATION_ERR: 13, NAMESPACE_ERR: 14, INVALID_ACCESS_ERR: 15, VALIDATION_ERR: 16, TYPE_MISMATCH_ERR: 17, SECURITY_ERR: 18, NETWORK_ERR: 19, ABORT_ERR: 20, URL_MISMATCH_ERR: 21, QUOTA_EXCEEDED_ERR: 22, TIMEOUT_ERR: 23, INVALID_NODE_TYPE_ERR: 24, DATA_CLONE_ERR: 25, code: 12 })
Error: Failed to execute 'measure' on 'Performance': The mark '[object Object]' does not exist.
    at logComponentTrigger (webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:4091:25 <- /tmp/_karma_webpack_197022/commons.js:22971:400)
    at commitPassiveMountOnFiber (webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:15737:15 <- /tmp/_karma_webpack_197022/commons.js:28439:266)
    at recursivelyTraversePassiveMountEffects (webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:15439:11 <- /tmp/_karma_webpack_197022/commons.js:28368:13)
    at commitPassiveMountOnFiber (webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:15519:11 <- /tmp/_karma_webpack_197022/commons.js:28389:17)
    at flushPassiveEffects (webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:18432:9 <- /tmp/_karma_webpack_197022/commons.js:29608:13)
    at webpack:///node_modules/react-dom/cjs/react-dom-client.development.js:17923:15 <- /tmp/_karma_webpack_197022/commons.js:29357:17
    at flushActQueue (webpack:///node_modules/react/cjs/react.development.js:590:34 <- /tmp/_karma_webpack_197022/commons.js:37742:44)
...

View all

ℹ️ Info

❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 70.27%
• Overall Coverage: 77.15% (-0.04%)

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: 5ea0e10 | Docs | Datadog PR Page | Was this helpful? Give us feedback!}

BeltranBulbarellaDD · 2026-02-25T14:03:24Z

packages/rum-react/src/domain/nextjs/datadogRumProvider.spec.tsx

+
+    let forceUpdate: () => void
+
+    function App() {


I'm not sure I love the idea of doing a component in a unit test. I would prefer to put it in a e2e test and here test behaviour.

BeltranBulbarellaDD · 2026-02-25T14:04:00Z

packages/rum-react/src/domain/nextjs/datadogRumProvider.tsx

+  return <>{children}</>
+}
+
+DatadogRumProvider.displayName = 'DatadogRumProvider'


Question: What is displayName this for?

It's just for the React Browser Extension to be able to display the component name in the React Virtual DOM tree. This is optional but nice to have

BeltranBulbarellaDD · 2026-02-25T14:05:48Z

packages/rum-react/src/entries/nextjs.ts

+ *   return (
+ *     <html>
+ *       <body>
+ *         <DatadogRumProvider>{children}</DatadogRumProvider>


I am stealing the following question since it was asked to me too:
Question: Why is this a Provider if it's not wrapping anything? Could it be a function call too?

Yeah, indeed, it can be implemented as a hook for example. We can't make it a pure function call because we have to call hooks in it, but hooks approach could work, I agree

BeltranBulbarellaDD · 2026-02-25T14:06:12Z

packages/rum-react/package.json

  "devDependencies": {
    "@types/react": "19.2.14",
    "@types/react-dom": "19.2.3",
+    "next": "15.2.2",


Question:: So we will support next >= 15.2.2. Shouldn't we try to support sooner versions too?
Suggestion:: For example support version >= 13?

No, that's just the version we use inside our integration. As it is defined above in the peerDependencies section, this approach supports all the versions >= 13

BeltranBulbarellaDD · 2026-02-25T14:07:24Z

test/apps/nextjs-app/app.tsx

+import {
+  reactPlugin,
+  UNSTABLE_ReactComponentTracker as ReactComponentTracker,
+  ErrorBoundary,


Suggestion: The thing about this is that NextJS has a different signature to report errors.
export default function ErrorPage({ error, reset, }:
So the React Error Boundary would not have the whole context. So we would need to make something for it.

Yeah, tbh I didn't look too much into sample app implementation made by AI, so it probably has a lots of problems which you raised

BeltranBulbarellaDD · 2026-02-25T14:08:50Z

test/apps/nextjs-app/app.tsx

+  datadogRum.setGlobalContext(window.RUM_CONTEXT)
+}
+
+function Link({


Question: Isn't this a Next component? Why do we have to re-declare it?

BeltranBulbarellaDD · 2026-02-25T14:10:03Z

test/apps/nextjs-app/app.tsx

+  )
+}
+
+function App() {


This is not how App Router works for routes. Each file is it's own route. Doc

This is important so that we use NextJS specific behaviour like client and server components and even prefetching and test against it.

BeltranBulbarellaDD · 2026-02-25T14:11:52Z

test/apps/nextjs-app/mockNextNavigation.tsx

+  return useContext(NavigationContext).navigate
+}
+
+export function NavigationProvider({


Question: What is this component for? Would customer need to create this file themselves? Shouldn't this be handled on the SDK side?

BeltranBulbarellaDD · 2026-02-25T14:13:30Z

test/e2e/scenario/reactPlugin.scenario.ts

+    test.describe(`with ${description}`, () => {
+      createTest('should define a view name with DatadogRumProvider')
+        .withRum()
+        .withReactApp(appName)


Question: Why are using ReactApp and not NextApp. IIUC, here you are serving the static html files to the tests, a NextApp needs it's own server to run so as to leverage NextJS features like prefetching, server components, cache, etc.

BeltranBulbarellaDD · 2026-02-25T14:13:48Z

test/e2e/scenario/reactPlugin.scenario.ts

+
+          // Firefox may delay dispatching error events from React error boundaries,
+          // causing flushEvents() to miss them, this timeout ensures the RUM event is captured.
+          if (browserName === 'firefox') {


I'm not soo sure about this.

lierniel added 4 commits February 24, 2026 19:22

feat(nextjs): added plugin configuration and packgae infrastructure

bd942c0

feat(nextjs): implemented view name computation

54637c9

feat(nextjs): implemented Provider component and view tracking logic

3acc527

test(nextjs): implemented sample app and added e2e tests

5ea0e10

BeltranBulbarellaDD reviewed Feb 25, 2026

View reviewed changes

Conversation

lierniel commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✨ Add Next.js App Router integration for @datadog/browser-rum-react

Motivation

Changes

Test instructions

Checklist

Uh oh!

github-actions bot commented Feb 25, 2026

Uh oh!

datadog-official bot commented Feb 25, 2026 • edited by datadog-datadog-prod-us1-2 bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Warnings

ℹ️ Info

Uh oh!

BeltranBulbarellaDD Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lierniel Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lierniel Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lierniel Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lierniel Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BeltranBulbarellaDD Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lierniel commented Feb 25, 2026 •

edited

Loading

✨ Add Next.js App Router integration for `@datadog/browser-rum-react`

datadog-official bot commented Feb 25, 2026 •

edited by datadog-datadog-prod-us1-2 bot

Loading

BeltranBulbarellaDD Feb 25, 2026 •

edited

Loading

BeltranBulbarellaDD Feb 25, 2026 •

edited

Loading

BeltranBulbarellaDD Feb 25, 2026 •

edited

Loading

lierniel Feb 25, 2026 •

edited

Loading

BeltranBulbarellaDD Feb 25, 2026 •

edited

Loading

BeltranBulbarellaDD Feb 25, 2026 •

edited

Loading

BeltranBulbarellaDD Feb 25, 2026 •

edited

Loading

BeltranBulbarellaDD Feb 25, 2026 •

edited

Loading

BeltranBulbarellaDD Feb 25, 2026 •

edited

Loading