--- title: Next.js description: >- Monitor Next.js applications with automatic route tracking for App Router and Pages Router using Datadog RUM breadcrumbs: Docs > Integrations > Next.js --- # Next.js Supported OS Integration version1.0.0 {% callout %} # Important note for users on the following Datadog sites: us2.ddog-gov.com {% alert level="info" %} To find out if this integration is available in your organization, see your [Datadog Integrations](https://app.datadoghq.com/integrations) page or ask your organization administrator. To initiate an exception request to enable this integration for your organization, email [support@ddog-gov.com](mailto:support@ddog-gov.com). {% /alert %} {% /callout %} ## Overview{% #overview %} The Datadog RUM Next.js integration provides framework-specific instrumentation to help you monitor and debug Next.js applications. This integration adds: - **Automatic route change detection** for both the App Router and Pages Router - **View name normalization** that converts dynamic route segments into parameterized names (e.g. `/users/123` becomes `/users/[id]`) - **Error reporting** with built-in components for Next.js error boundaries - **Full-stack visibility** by correlating frontend performance with backend traces and logs 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. ## Prerequisites{% #prerequisites %} Both routers require Next.js v15.3+, which supports the [instrumentation-client](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation-client) file convention. ## Setup{% #setup %} Start by setting up [Datadog RUM](https://docs.datadoghq.com/real_user_monitoring/browser/setup/client.md) in your Next.js application: - If you are creating a RUM application, select **Next.js** as the application type. - If Next.js is not available as an option, select **React** and follow the steps below to integrate the plugin manually. After configuration, the Datadog App provides instructions for integrating the [RUM-Next.js plugin](https://www.npmjs.com/package/@datadog/browser-rum-nextjs) with the Browser SDK. If Next.js is not available as an app type, or to configure manually, follow the steps below. ## App router usage{% #app-router-usage %} ### 1. Create an `instrumentation-client.js` file in the root of your Next.js project Initialize the Datadog RUM SDK with the `nextjsPlugin` and re-export `onRouterTransitionStart` so Next.js can call it on client-side navigations: ```js import { datadogRum } from '@datadog/browser-rum' import { nextjsPlugin, onRouterTransitionStart } from '@datadog/browser-rum-nextjs' export { onRouterTransitionStart } datadogRum.init({ applicationId: '', clientToken: '', site: 'datadoghq.com', plugins: [nextjsPlugin()], }) ``` ### 2. Call the DatadogAppRouter component from your root layout ```tsx // app/layout.tsx import { DatadogAppRouter } from '@datadog/browser-rum-nextjs' export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` ### 3. Report errors from error boundaries 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. Error behavior differs by component type: - **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. - **Client Component errors**: `error.message` is the original message and `digest` is absent. ```tsx // app/error.tsx (or app/dashboard/error.tsx, etc.) 'use client' import { useEffect } from 'react' import { addNextjsError } from '@datadog/browser-rum-nextjs' export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) { useEffect(() => { addNextjsError(error) }, [error]) return } ``` For errors in the **root layout**, use `global-error.tsx`; it must provide its own `` and `` tags since the root layout is replaced: ```tsx // app/global-error.tsx 'use client' import { useEffect } from 'react' import { addNextjsError } from '@datadog/browser-rum-nextjs' export default function GlobalError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) { useEffect(() => { addNextjsError(error) }, [error]) return ( ) } ``` For details on how view names are normalized from dynamic route segments, see Route tracking. ## Pages router usage{% #pages-router-usage %} ### 1. Create an `instrumentation-client.js` file in the root of your Next.js project Initialize the Datadog RUM SDK with the `nextjsPlugin`. The `onRouterTransitionStart` export is **not needed** for Pages Router. ```js import { datadogRum } from '@datadog/browser-rum' import { nextjsPlugin } from '@datadog/browser-rum-nextjs' datadogRum.init({ applicationId: '', clientToken: '', site: 'datadoghq.com', plugins: [nextjsPlugin()], }) ``` ### 2. Call the DatadogPagesRouter component from your custom App. ```tsx // pages/_app.tsx import type { AppProps } from 'next/app' import { DatadogPagesRouter } from '@datadog/browser-rum-nextjs' export default function MyApp({ Component, pageProps }: AppProps) { return ( <> ) } ``` ### 3. Report errors from error boundaries Use the `ErrorBoundary` component in your custom App to catch React rendering errors and report them to Datadog RUM: ```tsx // pages/_app.tsx import type { AppProps } from 'next/app' import { DatadogPagesRouter, ErrorBoundary } from '@datadog/browser-rum-nextjs' export default function MyApp({ Component, pageProps }: AppProps) { return ( <> (

Something went wrong

)} > ) } ``` For details on how view names are normalized from dynamic route segments, see Route tracking below. ## Route tracking{% #route-tracking %} The `DatadogPagesRouter` and `DatadogAppRouter` components automatically track route changes and normalize dynamic segments into parameterized view names: | Actual URL | View name | | ---------------------- | -------------------------------- | | `/about` | `/about` | | `/users/123` | `/users/[id]` | | `/users/123/posts/456` | `/users/[userId]/posts/[postId]` | | `/docs/a/b/c` | `/docs/[...slug]` | ## Go further with Datadog Next.js integration{% #go-further-with-datadog-nextjs-integration %} ### Traces{% #traces %} Connect your RUM and trace data to get a complete view of your application's performance. See [Connect RUM and Traces](https://docs.datadoghq.com/real_user_monitoring/platform/connect_rum_and_traces.md?tab=browserrum). ### Logs{% #logs %} To forward your Next.js application's logs to Datadog, see [JavaScript Logs Collection](https://docs.datadoghq.com/logs/log_collection/javascript.md). ### Metrics{% #metrics %} To generate custom metrics from your RUM application, see [Generate Metrics](https://docs.datadoghq.com/real_user_monitoring/generate_metrics.md). ## Troubleshooting{% #troubleshooting %} Need help? Contact [Datadog Support](https://docs.datadoghq.com/help/).