✨ NextJS Add addNextJSError component

[BeltranBulbarellaDD]

Motivation

Discussed in this RFC specifically here

Changes

(AI written)

Adds addNextjsError(error, context?) and NextjsErrorBoundary to @datadog/browser-rum-nextjs — the integration points for reporting errors from Next.js error boundaries to Datadog RUM.

addNextjsError(error, context?)

• Tags every error with framework: 'nextjs' context
• Adds nextjs.digest context when the error carries a digest property (server component errors — the hash links client-side errors to server-side logs)
• Uses onRumStart deferred callback so calls before SDK init are buffered and replayed
• Reserved fields (framework, nextjs.digest) are always applied last in the context merge, so user-provided context cannot overwrite them

NextjsErrorBoundary

• React class component wrapping addNextjsError for Pages Router client-side error catching
• Accepts a fallback render prop (NextjsErrorBoundaryFallback) and an optional onError callback
• Automatically calls addNextjsError in componentDidCatch

Test app & E2E

• Renamed test app from nextjs-app-router → nextjs (now covers both App Router and Pages Router)
• Added Pages Router test pages: pages-router/ index, user, guides, error boundary test
• E2E scenarios cover: router navigation (app + pages), client error (app + pages), server error with digest (app router), global error (app router), NextjsErrorBoundary catch + reset (pages router)

Both APIs exported from @datadog/browser-rum-nextjs main entry.

Test instructions

(AI written)

# Unit tests
yarn test:unit --spec packages/rum-nextjs/src/domain/error/addNextjsError.spec.ts

# E2E tests
yarn test:e2e -g "nextjs"

Navigating into test/apps/nextjs you can do yarn dev or yarn start (for production) and use the developer extension to test the events.

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

[cit-pr-commenter-54b7da]

Bundles Sizes Evolution

📦 Bundle Name	Base Size	Local Size	𝚫	𝚫%	Status
Rum	174.53 KiB	174.53 KiB	0 B	0.00%	✅
Rum Profiler	6.16 KiB	6.16 KiB	0 B	0.00%	✅
Rum Recorder	27.46 KiB	27.46 KiB	0 B	0.00%	✅
Logs	56.84 KiB	56.84 KiB	0 B	0.00%	✅
Flagging	944 B	944 B	0 B	0.00%	✅
Rum Slim	130.21 KiB	130.21 KiB	0 B	0.00%	✅
Worker	23.63 KiB	23.63 KiB	0 B	0.00%	✅

🚀 CPU Performance

Action Name	Base CPU Time (ms)	Local CPU Time (ms)	𝚫%
addglobalcontext	N/A	0.0047	N/A
addaction	N/A	0.0163	N/A
adderror	N/A	0.0172	N/A
addtiming	N/A	0.0045	N/A
startview	N/A	0.0174	N/A
startstopsessionreplayrecording	N/A	0.0008	N/A
logmessage	N/A	0.0194	N/A

🧠 Memory Performance

Action Name	Base Memory Consumption	Local Memory Consumption	𝚫
addglobalcontext	N/A	26.21 KiB	N/A
addaction	N/A	51.26 KiB	N/A
addtiming	N/A	27.07 KiB	N/A
adderror	N/A	54.99 KiB	N/A
startstopsessionreplayrecording	N/A	25.62 KiB	N/A
startview	N/A	452.01 KiB	N/A
logmessage	N/A	44.42 KiB	N/A

🔗 RealWorld

[datadog-prod-us1-3]

✅ Tests

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage (details)
• Patch Coverage: 75.00%
• Overall Coverage: 77.24% (+0.02%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: f7678cb | Docs | Datadog PR Page | Was this helpful? React with 👍/👎 or give us feedback!}

[BeltranBulbarellaDD]

@codex pls review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 673952b723

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f7678cbe8b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Sanitize user context before sending addNextjsError event

This path spreads context directly into the raw RUM event, but unlike rumPublicApi.addError it never calls sanitize first. When callers pass non-serializable values (for example circular objects or framework objects inside context), event serialization can fall back to '<error: unable to serialize object>', which can make the emitted line invalid and effectively drop the error payload instead of reporting it. Sanitizing the provided context before building context keeps addNextjsError behavior aligned with the core API.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve caller context precedence when merging raw error context

The merge order here gives rawError.context (derived from error.dd_context) precedence over the explicit context argument, and does a shallow object spread. In collisions, caller-provided fields are overwritten (or nested fields are lost) even though the regular addError path uses combine(rawError.context, context) so explicit context wins and nested keys merge. This makes addNextjsError produce inconsistent context data for the same inputs.

Useful? React with 👍 / 👎.