doc: instrumentation-client (#77649)

Author: gaojude

docs/01-app/03-building-your-application/06-optimizing/08-analytics.mdx

@@ -7,6 +7,23 @@ description: Measure and track page performance using Next.js Speed Insights
 
 Next.js has built-in support for measuring and reporting performance metrics. You can either use the `useReportWebVitals` hook to manage reporting yourself, or alternatively, Vercel provides a [managed service](https://vercel.com/analytics?utm_source=next-site&utm_medium=docs&utm_campaign=next-website) to automatically collect and visualize metrics for you.
 
+## Client Instrumentation
+
+For more advanced analytics and monitoring needs, Next.js provides a `instrumentation-client.js|ts` file that runs before your application's frontend code starts executing. This is ideal for setting up global analytics, error tracking, or performance monitoring tools.
+
+To use it, create an `instrumentation-client.js` or `instrumentation-client.ts` file in your application's root directory:
+
+```js filename="instrumentation-client.js"
+// Initialize analytics before the app starts
+console.log('Analytics initialized')
+
+// Set up global error tracking
+window.addEventListener('error', (event) => {
+  // Send to your error tracking service
+  reportError(event.error)
+})
+```
+
 ## Build Your Own
 
 <PagesOnly>

docs/01-app/04-api-reference/03-file-conventions/instrumentation-client.mdx

@@ -0,0 +1,40 @@
+---
+title: instrumentation-client.js
+description: Learn how to add client-side instrumentation to track and monitor your Next.js application's frontend performance.
+---
+
+The `instrumentation-client.js|ts` file allows you to add monitoring and analytics code that runs before your application's frontend code starts executing. This is useful for setting up performance tracking, error monitoring, or any other client-side observability tools.
+
+To use it, place the file in the **root** of your application or inside a `src` folder.
+
+## Usage
+
+Unlike [server-side instrumentation](/docs/app/building-your-application/optimizing/instrumentation), you don't need to export any specific functions. Simply write your monitoring code directly in the file:
+
+```ts filename="instrumentation-client.ts" switcher
+// Set up performance monitoring
+performance.mark('app-init')
+
+// Initialize analytics
+console.log('Analytics initialized')
+
+// Set up error tracking
+window.addEventListener('error', (event) => {
+  // Send to your error tracking service
+  reportError(event.error)
+})
+```
+
+```js filename="instrumentation-client.js" switcher
+// Set up performance monitoring
+performance.mark('app-init')
+
+// Initialize analytics
+console.log('Analytics initialized')
+
+// Set up error tracking
+window.addEventListener('error', (event) => {
+  // Send to your error tracking service
+  reportError(event.error)
+})
+```

docs/01-app/04-api-reference/05-config/01-next-config-js/clientInstrumentationHook.mdx

@@ -240,9 +240,6 @@ export function getDefineEnv({
     'process.env.__NEXT_TELEMETRY_DISABLED': Boolean(
       process.env.NEXT_TELEMETRY_DISABLED
     ),
-    'process.env.__NEXT_EXPERIMENTAL_CLIENT_INSTRUMENTATION_HOOK': Boolean(
-      config.experimental.clientInstrumentationHook
-    ),
     ...(isNodeOrEdgeCompilation
       ? {
           // Fix bad-actors in the npm ecosystem (e.g. `node-formidable`)

packages/next/src/build/webpack/plugins/define-env-plugin.ts

@@ -4,30 +4,28 @@
  * The `private-next-instrumentation-client` module is automatically aliased to
  * the `instrumentation-client.ts` file in the project root by webpack or turbopack.
  */
-if (process.env.__NEXT_EXPERIMENTAL_CLIENT_INSTRUMENTATION_HOOK) {
-  if (process.env.NODE_ENV === 'development') {
-    const measureName = 'Client Instrumentation Hook'
-    const startTime = performance.now()
-    require('private-next-instrumentation-client')
-    const endTime = performance.now()
+if (process.env.NODE_ENV === 'development') {
+  const measureName = 'Client Instrumentation Hook'
+  const startTime = performance.now()
+  require('private-next-instrumentation-client')
+  const endTime = performance.now()
 
-    const duration = endTime - startTime
-    performance.measure(measureName, {
-      start: startTime,
-      end: endTime,
-      detail: 'Client instrumentation initialization',
-    })
+  const duration = endTime - startTime
+  performance.measure(measureName, {
+    start: startTime,
+    end: endTime,
+    detail: 'Client instrumentation initialization',
+  })
 
-    // Using 16ms threshold as it represents one frame (1000ms/60fps)
-    // This helps identify if the instrumentation hook initialization
-    // could potentially cause frame drops during development.
-    const THRESHOLD = 16
-    if (duration > THRESHOLD) {
-      console.log(
-        `[${measureName}] Slow execution detected: ${duration.toFixed(0)}ms (Note: Code download overhead is not included in this measurement)`
-      )
-    }
-  } else {
-    require('private-next-instrumentation-client')
+  // Using 16ms threshold as it represents one frame (1000ms/60fps)
+  // This helps identify if the instrumentation hook initialization
+  // could potentially cause frame drops during development.
+  const THRESHOLD = 16
+  if (duration > THRESHOLD) {
+    console.log(
+      `[${measureName}] Slow execution detected: ${duration.toFixed(0)}ms (Note: Code download overhead is not included in this measurement)`
+    )
   }
+} else {
+  require('private-next-instrumentation-client')
 }

packages/next/src/lib/require-instrumentation-client.ts

@@ -457,7 +457,6 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
             buildTimeThresholdMs: z.number().int(),
           })
           .optional(),
-        clientInstrumentationHook: z.boolean().optional(),
       })
       .optional(),
     exportPathMap: z