Skip to content

Commit ca12a26

Browse files
BeltranBulbarellaDDBeltranBulbarellaDD
authored
🔧 Add Next.js documentation and make package public (#4384)
1 parent ad49faa commit ca12a26

File tree

2 files changed

+139
-10
lines changed

2 files changed

+139
-10
lines changed

‎packages/rum-nextjs/README.md‎

Lines changed: 138 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,32 @@
11
# RUM Browser Monitoring - NEXTJS integration
22

3-
This package provides NextJS integration for Datadog Browser RUM, supporting both the App Router and Pages Router.
3+
**Note**: This integration is in Preview. Features and configuration are subject to change.
44

5-
Both routers require **Next.js v15.3+**, which supports the [`instrumentation-client`][1] file convention.
5+
## Overview
66

7-
[1]: https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation-client
7+
The Datadog RUM Next.js integration provides framework-specific instrumentation to help you monitor and debug Next.js applications. This integration adds:
88

9-
# App Router Usage
9+
- **Automatic route change detection** for both the App Router and Pages Router
10+
- **View name normalization** that converts dynamic route segments into parameterized names (e.g. `/users/123` becomes `/users/[id]`)
11+
- **Error reporting** with built-in components for Next.js error boundaries
12+
- **Full-stack visibility** by correlating frontend performance with backend traces and logs
1013

11-
## 1. Create an `instrumentation-client.js` file in the root of your Next.js project
14+
Combined with Datadog RUM's core capabilities, you can debug performance bottlenecks, track user journeys, monitor Core Web Vitals, and analyze every user session with context.
15+
16+
## Setup
17+
18+
Start by setting up [Datadog RUM][1] in your Next.js application:
19+
20+
- If you are creating a RUM application, select **Next.js** as the application type.
21+
- If Next.js is not available as an option, select **React** and follow the steps below to integrate the plugin manually.
22+
23+
After configuration, the Datadog App provides instructions for integrating the [RUM-Next.js plugin][2] with the Browser SDK.
24+
25+
Both routers require **Next.js v15.3+**, which supports the [`instrumentation-client`][3] file convention.
26+
27+
## App router usage
28+
29+
### 1. Create an `instrumentation-client.js` file in the root of your Next.js project
1230

1331
Initialize the Datadog RUM SDK with the `nextjsPlugin` and re-export `onRouterTransitionStart` so Next.js can call it on client-side navigations:
1432

@@ -26,7 +44,7 @@ datadogRum.init({
2644
})
2745
```
2846

29-
## 2. Call the DatadogAppRouter component from your root layout.
47+
### 2. Call the DatadogAppRouter component from your root layout.
3048

3149
```tsx
3250
// app/layout.tsx
@@ -44,9 +62,55 @@ export default function RootLayout({ children }: { children: React.ReactNode })
4462
}
4563
```
4664

47-
# Pages Router Usage
65+
### 3. Report errors from error boundaries
66+
67+
Next.js uses [error boundaries](https://nextjs.org/docs/app/api-reference/file-conventions/error) (`error.tsx` files) to catch uncaught exceptions in each route segment. Use `addNextjsError` inside these boundaries to report errors to Datadog RUM.
68+
69+
For **Server Component** errors, Next.js sends a generic message to the client and attaches `error.digest`, a hash that links the client-side error to your server-side logs. For **Client Component** errors, `error.message` is the original message and `digest` is absent.
70+
71+
```tsx
72+
// app/error.tsx (or app/dashboard/error.tsx, etc.)
73+
'use client'
74+
75+
import { useEffect } from 'react'
76+
import { addNextjsError } from '@datadog/browser-rum-nextjs'
77+
78+
export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
79+
useEffect(() => {
80+
addNextjsError(error)
81+
}, [error])
82+
83+
return <button onClick={reset}>Try again</button>
84+
}
85+
```
86+
87+
For errors in the **root layout**, use `global-error.tsx`; it must provide its own `<html>` and `<body>` tags since the root layout is replaced:
88+
89+
```tsx
90+
// app/global-error.tsx
91+
'use client'
92+
93+
import { useEffect } from 'react'
94+
import { addNextjsError } from '@datadog/browser-rum-nextjs'
95+
96+
export default function GlobalError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
97+
useEffect(() => {
98+
addNextjsError(error)
99+
}, [error])
100+
101+
return (
102+
<html>
103+
<body>
104+
<button onClick={reset}>Try again</button>
105+
</body>
106+
</html>
107+
)
108+
}
109+
```
110+
111+
## Pages router usage
48112

49-
## 1. Create an `instrumentation-client.js` file in the root of your Next.js project
113+
### 1. Create an `instrumentation-client.js` file in the root of your Next.js project
50114

51115
Initialize the Datadog RUM SDK with the `nextjsPlugin`. The `onRouterTransitionStart` export is **not needed** for Pages Router.
52116

@@ -62,7 +126,7 @@ datadogRum.init({
62126
})
63127
```
64128

65-
## 2. Call the DatadogPagesRouter component from your custom App.
129+
### 2. Call the DatadogPagesRouter component from your custom App.
66130

67131
```tsx
68132
// pages/_app.tsx
@@ -78,3 +142,68 @@ export default function MyApp({ Component, pageProps }: AppProps) {
78142
)
79143
}
80144
```
145+
146+
### 3. Report errors from error boundaries
147+
148+
Use the `ErrorBoundary` component in your custom App to catch React rendering errors and report them to Datadog RUM:
149+
150+
```tsx
151+
// pages/_app.tsx
152+
import type { AppProps } from 'next/app'
153+
import { DatadogPagesRouter, ErrorBoundary } from '@datadog/browser-rum-nextjs'
154+
155+
export default function MyApp({ Component, pageProps }: AppProps) {
156+
return (
157+
<>
158+
<DatadogPagesRouter />
159+
<ErrorBoundary
160+
fallback={({ resetError }) => (
161+
<div>
162+
<p>Something went wrong</p>
163+
<button onClick={resetError}>Try again</button>
164+
</div>
165+
)}
166+
>
167+
<Component {...pageProps} />
168+
</ErrorBoundary>
169+
</>
170+
)
171+
}
172+
```
173+
174+
## Route tracking
175+
176+
The `DatadogPagesRouter` and `DatadogAppRouter` components automatically track route changes and normalize dynamic segments into parameterized view names:
177+
178+
| Actual URL | View name |
179+
| ---------------------- | -------------------------------- |
180+
| `/about` | `/about` |
181+
| `/users/123` | `/users/[id]` |
182+
| `/users/123/posts/456` | `/users/[userId]/posts/[postId]` |
183+
| `/docs/a/b/c` | `/docs/[...slug]` |
184+
185+
## Go further with Datadog Next.js integration
186+
187+
### Traces
188+
189+
Connect your RUM and trace data to get a complete view of your application's performance. See [Connect RUM and Traces][4].
190+
191+
### Logs
192+
193+
To forward your Next.js application's logs to Datadog, see [JavaScript Logs Collection][5].
194+
195+
### Metrics
196+
197+
To generate custom metrics from your RUM application, see [Generate Metrics][6].
198+
199+
## Troubleshooting
200+
201+
Need help? Contact [Datadog Support][7].
202+
203+
[1]: https://docs.datadoghq.com/real_user_monitoring/browser/setup/client
204+
[2]: https://www.npmjs.com/package/@datadog/browser-rum-nextjs
205+
[3]: https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation-client
206+
[4]: https://docs.datadoghq.com/real_user_monitoring/platform/connect_rum_and_traces/?tab=browserrum
207+
[5]: https://docs.datadoghq.com/logs/log_collection/javascript/
208+
[6]: https://docs.datadoghq.com/real_user_monitoring/generate_metrics
209+
[7]: https://docs.datadoghq.com/help/

‎packages/rum-nextjs/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@datadog/browser-rum-nextjs",
3-
"private": true,
3+
"version": "6.31.0",
44
"license": "Apache-2.0",
55
"main": "cjs/entries/main.js",
66
"module": "esm/entries/main.js",

0 commit comments

Comments
 (0)