@@ -87,6 +87,10 @@ The `instrumentation-client.js` file executes at a specific point in the applica
...
@@ -87,6 +87,10 @@ The `instrumentation-client.js` file executes at a specific point in the applica
This timing makes it ideal for setting up error tracking, analytics, and performance monitoring that needs to capture early application lifecycle events.
This timing makes it ideal for setting up error tracking, analytics, and performance monitoring that needs to capture early application lifecycle events.
## See also
`next.config.js` plugins (for example, wrappers like `withSentry`) can register their own client instrumentation module via the [`instrumentationClientInject`](/docs/app/api-reference/config/next-config-js/instrumentationClientInject) option. Injected modules run before this file, in array order, and may export their own `onRouterTransitionStart`. Application code should continue to use this file convention directly.
description: Inject additional client-side instrumentation modules before the user's `instrumentation-client.{js,ts}` file.
---
`instrumentationClientInject` is a list of modules that are imported on the client for their side effects before the user's [`instrumentation-client.{js,ts}`](/docs/app/api-reference/file-conventions/instrumentation-client) file runs, ahead of React hydration.
This option is primarily intended for **`next.config.js` plugins** (for example, wrappers like `withSentry` or `withAnalytics` that extend a project's config). It lets such a plugin inject its own client instrumentation module — including a navigation hook — without requiring every project to author or modify an `instrumentation-client` file. Application code should generally continue to use the [`instrumentation-client.{js,ts}`](/docs/app/api-reference/file-conventions/instrumentation-client) file convention directly.
A plugin typically appends its own module to whatever the project already has configured:
```js filename="withMyInstrumentation.js"
module.exports = function withMyInstrumentation(nextConfig = {}) {
- A bare npm package name, resolved from the project's `node_modules`.
- A path relative to the project root.
## Execution order
Modules run on the client in this order:
1. Each entry in `instrumentationClientInject`, in array order.
2. The project's `instrumentation-client.{js,ts}` file, if present.
3. React hydration.
## Router navigation hook
Each injected module may optionally export an `onRouterTransitionStart` function with the same signature as the one documented for the [`instrumentation-client` file convention](/docs/app/api-reference/file-conventions/instrumentation-client#router-navigation-tracking). Next.js composes a single hook that fans out to every exported `onRouterTransitionStart` on each navigation, calling them in array order, with the user file's hook running last.
```js filename="lib/sentry-client.js"
// Side-effectful setup runs at load time.
setupSentry()
export function onRouterTransitionStart(url, navigationType) {
recordNavigationBreadcrumb(url, navigationType)
}
```
Modules that do not export `onRouterTransitionStart` are skipped during navigation.