Client-side instrumentation

[amannn]

Goals

Allow to register client-only code in instrumentation.ts.

Background

instrumentation.ts is currently available for code that executes in Node.js and Edge. However, as far as I know, there is currently no equivalent that is called for the client side.

Error-tracking libraries like Sentry currently enable client-side instrumentation, by wrapping each client-side entry point and injecting a custom script into the build.

While this works, I'd argue it's somewhat brittle and also requires quite some custom logic to work. Instead, I'd find it very helpful if Next.js would expose a built-in way that covers this.

My particular use case is adapting the error handling capabilities of next-intl to register a global error handler that is automatically called in all environments if registered in instrumentation.ts.

/cc @lforst in case you're interested in this too

Related: #57563

Proposal

export async function register() {
  // ✨ New
  if (process.env.NEXT_RUNTIME === 'client') {
    await import('./instrumentation-client')
  }

  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }
 
  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}

[lforst]

Random additional input here: It would be crucial to have something similar to the onRequestError hook for client-side Pages Router errors. Currently, Next.js simply swallows all the rendering errors. With the Sentry SDK, we apply build-time instrumentation to wrap all Pages in the pages router during the build to report errors that happen during the render cycle. This is quite fragile and also not doable with Turbopack.

[mderazon]

Also interested in sending otel traces from client side. Would be nice in Next.js did that as adding tracing to the frontend code is currently complicated:

• https://opentelemetry.io/blog/2022/frontend-overhaul/#opentelemetry-instrumentation
• https://github.com/open-telemetry/opentelemetry-demo/tree/395f38572d4b1352883712cc080d6894f5f9faf8/src/frontend/utils/telemetry

Having end-to-end traces could nice

[Netail]

Another use-case; Initializing Grafana Faro

[Netail]

Look what we have here; #76916 👀

[shirahamax]

@gaojude

Hello, thank you for adding the clientInstrumentationHook feature :)

I recently upgraded my product to version 15.3 and noticed that clientInstrumentationHook is still listed under ExperimentalConfig.
Would it be possible to remove this flag from ExperimentalConfig?
https://github.com/vercel/next.js/blob/v15.3.0/packages/next/src/server/config-shared.ts#L651

Also, may I ask another question?
The documentation only mentions in the App Router — is the Pages Router not supported?👀
https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation-client

[gaojude]

@gaojude

Hello, thank you for adding the clientInstrumentationHook feature :)

I recently upgraded my product to version 15.3 and noticed that clientInstrumentationHook is still listed under ExperimentalConfig.

Would it be possible to remove this flag from ExperimentalConfig?

https://github.com/vercel/next.js/blob/v15.3.0/packages/next/src/server/config-shared.ts#L651

Also, may I ask another question?

The documentation only mentions in the App Router — is the Pages Router not supported?👀

https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation-client

Both supported. We should fix the doc. cc @delbaoliveira

[shirahamax]

Thank you for your reply. I understand :)

[polaris-fullstack]

Thanks for the detailed write-up — I totally agree that having first-class support for client-side instrumentation in instrumentation.ts would simplify things a lot, especially for cross-environment error tracking setups.

At the moment, like you said, most workarounds rely on bundler-level injection or wrapping entry points with tools like Sentry or LogRocket. While they work, they often lead to fragile setups and extra maintenance overhead.

In my case, I’ve been experimenting with something like this:
if (typeof window !== "undefined") { // Simulate a client-side instrumentation hook window.addEventListener("error", (e) => { // Forward to custom logger or error tracking service console.error("Client-side error captured:", e); }); }
Not perfect — and it doesn't tie into instrumentation.ts, but it at least gets global error hooks on the client.

Ideally, Next.js could expose something like:
export function registerClientInstrumentation() { // Called automatically on the client, just like instrumentation.ts is on the server }
This would help unify error handling logic for libraries like next-intl and give more confidence across environments.

Really interested in what the core team thinks here — seems like a great DX improvement.