[pull] canary from vercel:canary

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

@@ -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.
 
+## 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.
+
 ## Examples
 
 ### Error tracking

docs/01-app/03-api-reference/05-config/01-next-config-js/instrumentationClientInject.mdx

@@ -0,0 +1,68 @@
+---
+title: instrumentationClientInject
+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 = {}) {
+  return {
+    ...nextConfig,
+    instrumentationClientInject: [
+      ...(nextConfig.instrumentationClientInject ?? []),
+      'my-instrumentation-package/client',
+    ],
+  }
+}
+```
+
+It can also be set directly:
+
+```js filename="next.config.js"
+/** @type {import('next').NextConfig} */
+module.exports = {
+  instrumentationClientInject: [
+    'my-analytics-package',
+    './lib/sentry-client.js',
+  ],
+}
+```
+
+Each entry is one of:
+
+- 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.
+
+## Version history
+
+| Version   | Changes                                  |
+| --------- | ---------------------------------------- |
+| `v16.3.0` | `instrumentationClientInject` introduced |

packages/next/errors.json

@@ -1250,10 +1250,31 @@
   "1249": "Route \"%s\": Next.js encountered uncached data during the initial render or a navigation.\\n\\n\\`fetch(...)\\` or \\`connection()\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the data access with \\`\"use cache\"\\`\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
   "1250": "Route \"%s\": Next.js encountered runtime data during the initial render or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Use \\`generateStaticParams\\` to make route params static\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
   "1251": "Route \"%s\": Next.js encountered runtime data during the initial render or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Use \\`generateStaticParams\\` to make route params static\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
-  "1252": "\\`experimental.cssChunking: \"graph\"\\` is only supported with Turbopack. Please remove the option or run Next.js with Turbopack in %s.",
-  "1253": "\\`experimental.cssChunking: \"strict\"\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
-  "1254": "\\`experimental.cssChunking: false\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
-  "1255": "Compilation failed but no issues were recorded",
-  "1256": "no route matched for path \"%s\"",
-  "1257": "compileRoute: either routeSpecifier or path is required"
+  "1252": "Route \"%s\": Next.js encountered runtime data in \\`generateViewport()\\`.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` in \\`generateViewport()\\` prevents the page from being prerendered, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Use a static viewport export instead of \\`generateViewport()\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/next-prerender-dynamic-viewport",
+  "1253": "Route \"%s\": Next.js encountered uncached or runtime data in \\`generateViewport()\\`.\\n\\nThis prevents the page from being prerendered, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Use a static viewport export instead of \\`generateViewport()\\`\\n  - Cache the viewport data with \\`\"use cache\"\\` in \\`generateViewport()\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/next-prerender-dynamic-viewport",
+  "1254": "Route \"%s\": Next.js encountered uncached or runtime data during the initial render.\\n\\n\\`fetch(...)\\`, \\`cookies()\\`, \\`headers()\\`, \\`params\\`, \\`searchParams\\`, or \\`connection()\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered, blocking navigation and leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the data access with \\`\"use cache\"\\`\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - If params are known, prerender them with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1255": "Route \"%s\": Next.js encountered uncached data in \\`generateViewport()\\`.\\n\\n\\`fetch(...)\\` or \\`connection()\\` in \\`generateViewport()\\` prevents the page from being prerendered, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the viewport data with \\`\"use cache\"\\` in \\`generateViewport()\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/next-prerender-dynamic-viewport",
+  "1256": "Route \"%s\": Next.js encountered %s in a Client Component.\\n\\nThis value would be evaluated during the prerender, instead of recomputed on each visit.\\n\\nWays to fix this:\\n  - Wrap the Client Component in \\`<Suspense fallback={...}>\\`\\n  - Move the read into a \\`useEffect\\` or event handler\\n%s\\nLearn more: %s",
+  "1257": "Route \"%s\": Next.js encountered runtime data during the initial render.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered, blocking navigation and leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - If params are known, prerender them with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1258": "Route \"%s\": Next.js encountered runtime data during the initial render or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - If params are known, prerender them with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1259": "Route \"%s\": Next.js encountered %s while prerendering.\\n\\nThis value can change between renders, so it must be either prerendered or computed later.\\n\\nWays to fix this:\\n  - Render at request time by adding a dynamic data access (e.g. \\`await connection()\\`) before this call\\n  - Prerender and cache the value with \\`\"use cache\"\\`\\n  - Render the value on the client with \\`\"use client\"\\`\\n%s\\nLearn more: %s",
+  "1260": "Route \"%s\": Next.js encountered runtime data during prerendering or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - If params are known, prerender them with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1261": "Route \"%s\": Next.js encountered the unstable value %s while prerendering.\\n\\nThis value can change between renders, so it must be either prerendered or computed later.\\n\\nWays to fix this:\\n  - Render at request time by adding a dynamic data access (e.g. \\`await connection()\\`) before this call\\n  - Prerender and cache the value with \\`\"use cache\"\\`\\n  - Render the value on the client with \\`\"use client\"\\`\\n%s\\nLearn more: %s",
+  "1262": "Route \"%s\": Next.js encountered uncached or runtime data during prerendering.\\n\\n\\`fetch(...)\\`, \\`cookies()\\`, \\`headers()\\`, \\`params\\`, \\`searchParams\\`, or \\`connection()\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the data access with \\`\"use cache\"\\`\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - If params are known, prerender them with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1263": "Route \"%s\": Next.js encountered runtime data during prerendering.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - If params are known, prerender them with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1264": "Route \"%s\": Next.js encountered uncached data during prerendering or a navigation.\\n\\n\\`fetch(...)\\` or \\`connection()\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the data access with \\`\"use cache\"\\`\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1265": "Route \"%s\": Next.js encountered uncached data during prerendering.\\n\\n\\`fetch(...)\\` or \\`connection()\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the data access with \\`\"use cache\"\\`\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1266": "Route \"%s\": Next.js encountered the unstable value %s in a Client Component.\\n\\nThis value would be evaluated during the prerender, instead of recomputed on each visit.\\n\\nWays to fix this:\\n  - Wrap the Client Component in \\`<Suspense fallback={...}>\\`\\n  - Move the read into a \\`useEffect\\` or event handler\\n%s\\nLearn more: %s",
+  "1267": "Route \"%s\": Next.js encountered runtime data during prerendering.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Prerender params if known with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1268": "Route \"%s\": Next.js encountered runtime data during prerendering or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Prerender params if known with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1269": "Route \"%s\": Next.js encountered uncached or runtime data during prerendering.\\n\\n\\`fetch(...)\\`, \\`cookies()\\`, \\`headers()\\`, \\`params\\`, \\`searchParams\\`, or \\`connection()\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the data access with \\`\"use cache\"\\`\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Prerender params if known with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1270": "Route \"%s\": Next.js encountered uncached or runtime data during prerendering.\\n\\n\\`fetch(...)\\`, \\`cookies()\\`, \\`headers()\\`, \\`params\\`, \\`searchParams\\`, or \\`connection()\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the data access with \\`\"use cache\"\\`\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - If the runtime data is \\`params\\` and they're known, prerender them with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1271": "Route \"%s\": Next.js encountered runtime data during prerendering or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - If the runtime data is \\`params\\` and they're known, prerender them with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1272": "Route \"%s\": Next.js encountered runtime data during prerendering.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - If the runtime data is \\`params\\` and they're known, prerender them with \\`generateStaticParams\\`\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1273": "\\`experimental.cssChunking: \"graph\"\\` is only supported with Turbopack. Please remove the option or run Next.js with Turbopack in %s.",
+  "1274": "\\`experimental.cssChunking: \"strict\"\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
+  "1275": "\\`experimental.cssChunking: false\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
+  "1276": "Compilation failed but no issues were recorded",
+  "1277": "no route matched for path \"%s\"",
+  "1278": "compileRoute: either routeSpecifier or path is required"
 }

packages/next/src/next-devtools/dev-overlay/components/errors/dialog/dialog.tsx

@@ -39,6 +39,7 @@ export const DIALOG_STYLES = `
 
   .error-overlay-dialog-scroll {
     overflow-y: auto;
+    scrollbar-gutter: stable;
     height: 100%;
   }
 `