Unverified Commit 8b57e82a authored by Jimmy Lai's avatar Jimmy Lai Committed by GitHub

router instrumentation: refactor client hook dispatch (1/7) (#94755)

## Stack Position

(1/7) in the router instrumentation stack.

1. **#94755: router instrumentation: refactor client hook dispatch
(1/7)**
2. #94766: router instrumentation: add transition start context (2/7)
3. #94756: router instrumentation: add transition commit events (3/7)
4. #94765: router instrumentation: add commit route and prefetch context
(4/7)
5. #94757: router instrumentation: add transition abort events (5/7)
6. #94758: router instrumentation: add route mismatch events (6/7)
7. #94737: router instrumentation: add transition settlement events
(7/7)

## What This PR Does

Refactors client instrumentation loading so webpack and Turbopack
provide an ordered array of instrumentation modules to a shared
router-transition dispatcher.

The existing config remains unchanged:

```ts
const nextConfig = {
  instrumentationClientInject: ['my-observability-library/client'],
}
```

## Motivation

This refactor lands first, ahead of the new lifecycle events, for two
reasons:

1. **Maintainability — the stack adds more hooks.** Previously the hook
fan-out was generated at build time (a composed
`onRouterTransitionStart` emitted by both the webpack loader and the
Turbopack import map). Each new event (commit, settled, abort, mismatch)
would require regenerating that composition in both bundlers, per hook.
Moving dispatch into one runtime module means new hooks are added once,
in a single place, with no new bundler composition logic per hook.

2. **Fault tolerance.** Dispatch now isolates failures across
instrumentation modules:
- A hook that throws is caught per module, so the remaining modules
still run for that navigation (previously, one throwing hook aborted the
rest).
- Modules whose exports are `null`/`undefined` (side-effect-only) are
filtered out instead of throwing (previously an unguarded existence
check could throw a `TypeError` and break hydration).

## Design

- Injected modules run in array order before the application
instrumentation file.
- With no injected modules, bundlers preserve the direct user
instrumentation alias and the runtime normalizes it to a one-element
array.
- Hooks are read from each module at dispatch time.
- A failing hook does not prevent later modules from running.
- Side-effect-only modules may export `null` or `undefined`.
- The dispatcher can support additional hooks without generating new
bundler composition logic for each hook.

## Not In This PR

- New event arguments or lifecycle hooks
- Transition IDs, timestamps, route data, or prefetch data

## Reviewer Focus

- Webpack and Turbopack produce the same ordered module array.
- Hook fan-out stays in the router-transition dispatcher.
- Ordering, dynamic hook lookup, and per-module error isolation are
preserved.

## Validation

- `pnpm --filter=next types`
- `cargo fmt --all -- --check`
- Instrumentation client E2E coverage in dev and production with webpack
and Turbopack
- Cache Components instrumentation client coverage

<!-- NEXT_JS_LLM_PR -->
Co-authored-by: 's avatarJude Gao <jude.gao@vercel.com>
parent 47ad350d
......@@ -1394,11 +1394,10 @@ fn insert_package_alias(import_map: &mut ImportMap, prefix: &str, package_root:
/// Handles instrumentation-client.ts bundling logic.
///
/// Resolves the `private-next-instrumentation-client` alias to a virtual module
/// that first requires each entry of `instrumentationClientInject` for side
/// effects (in array order) and then re-exports the user's
/// `instrumentation-client.{pageExt}` file via the
/// `private-next-instrumentation-client-user` alias.
/// Without injected modules, resolves `private-next-instrumentation-client`
/// directly to the user's `instrumentation-client.{pageExt}` file. Otherwise,
/// resolves it to a virtual module containing each injected module in array
/// order, followed by the user's instrumentation module.
async fn insert_instrumentation_client_alias(
import_map: &mut ImportMap,
project_path: FileSystemPath,
......@@ -1415,9 +1414,9 @@ async fn insert_instrumentation_client_alias(
ImportMapping::Ignore.resolved_cell(),
];
let injects = next_config.instrumentation_client_inject().await?;
let modules = next_config.instrumentation_client_inject().await?;
if injects.is_empty() {
if modules.is_empty() {
insert_alias_to_alternatives(
import_map,
rcstr!("private-next-instrumentation-client"),
......@@ -1434,25 +1433,18 @@ async fn insert_instrumentation_client_alias(
user_file_alternatives,
);
let injects = injects
let modules = modules
.iter()
.map(|s| s.as_str())
.chain(std::iter::once("private-next-instrumentation-client-user"));
let mut body = String::new();
for (i, spec) in injects.clone().enumerate() {
body.push_str(&format!(
"var mod_{i} = require({});\n",
serde_json::to_string(spec)?
));
}
body.push_str("module.exports = { onRouterTransitionStart(url, type) {\n");
for (i, _) in injects.enumerate() {
body.push_str(&format!(
" mod_{i}?.onRouterTransitionStart?.(url, type);\n"
));
let mut body = String::from("module.exports = [");
for (i, spec) in modules.enumerate() {
if i > 0 {
body.push(',');
}
body.push_str(&format!("require({})", serde_json::to_string(spec)?));
}
body.push_str("}};\n");
body.push_str("];\n");
let virtual_source = VirtualSource::new(
// Use cjs here in case the user has type:module in the package.json. We do intentionally
......
......@@ -152,11 +152,10 @@ export function createWebpackAliases({
// `private-next-instrumentation-client` resolves to a placeholder
// file whose contents are replaced at build time by
// `next-instrumentation-client-loader` (registered via a
// `module.rules` entry in webpack-config.ts). The emitted module
// requires each `instrumentationClientInject` entry for side effects,
// then re-exports the user's `instrumentation-client.{pageExt}` file
// (resolved through the `private-next-instrumentation-client-user`
// alias below).
// `module.rules` entry in webpack-config.ts). The emitted module lists
// each configured instrumentation module, followed by the user's
// `instrumentation-client.{pageExt}` file (resolved through the
// `private-next-instrumentation-client-user` alias below).
'private-next-instrumentation-client':
INSTRUMENTATION_CLIENT_STUB_PATH,
'private-next-instrumentation-client-user': [
......
......@@ -1953,16 +1953,15 @@ export default async function getBaseWebpackConfig(
sideEffects: false,
},
// The placeholder file aliased from `private-next-instrumentation-client`.
// The loader replaces its contents with a synthetic module that
// requires each `instrumentationClientInject` entry, then re-exports
// the user's `instrumentation-client.{pageExt}` (composing
// `onRouterTransitionStart` hooks across all of them).
// The loader replaces its contents with a synthetic module containing
// each `instrumentationClientInject` entry, followed by the user's
// `instrumentation-client.{pageExt}` module.
{
test: /[\\/]next[\\/]dist[\\/](esm[\\/])?build[\\/]webpack[\\/]loaders[\\/]instrumentation-client-stub\.js$/,
use: {
loader: 'next-instrumentation-client-loader',
options: {
injects: JSON.stringify(config.instrumentationClientInject),
modules: config.instrumentationClientInject,
},
},
},
......
import { promisify } from 'util'
import type { webpack } from 'next/dist/compiled/webpack/webpack'
/**
* Loader options for `next-instrumentation-client-loader`. The list of inject
* specifiers is JSON-stringified so it can travel through the loader query
* string.
*/
export type InstrumentationClientLoaderOptions = {
/** JSON-stringified `string[]` of module specifiers. */
injects: string
modules: string[]
}
const NextInstrumentationClientLoader: webpack.LoaderDefinitionFunction<InstrumentationClientLoaderOptions> =
function () {
const callback = this.async()
const { injects: injectsStringified } = this.getOptions()
const injects = JSON.parse(injectsStringified || '[]') as string[]
async function () {
const { modules } = this.getOptions()
// No injects: the alias is a transparent passthrough to the user's
// `instrumentation-client.{pageExt}` (or the empty module fallback).
if (injects.length === 0) {
callback(
null,
`module.exports = require('private-next-instrumentation-client-user');\n`
)
return
if (modules.length === 0) {
return `module.exports = require('private-next-instrumentation-client-user');\n`
}
// Resolve each inject specifier against the project root so the emitted
// Resolve each module specifier against the project root so the emitted
// `require()` calls don't get resolved relative to the stub's location
// inside `node_modules/next/`. Bare specifiers (npm package names) are
// resolved against the project's `node_modules`.
const resolve = promisify(this.resolve)
const resolve = this.getResolve()
const rootContext = this.rootContext
Promise.all(injects.map((spec) => resolve(rootContext, spec)))
.then((resolvedInjects) => {
const allModules = [
...resolvedInjects,
'private-next-instrumentation-client-user',
]
const lines: string[] = []
allModules.forEach((spec, i) => {
lines.push(`var mod_${i} = require(${JSON.stringify(spec)});`)
})
// Compose a single `onRouterTransitionStart` that fans out to every
// module's hook (when exported), in array order, with the user file's
// hook running last.
const hookCalls = allModules
.map(
// Webpack doesn't transpile this, so use a manual version of optional chaining.
(_, i) =>
` mod_${i} && mod_${i}.onRouterTransitionStart && mod_${i}.onRouterTransitionStart(url, type);`
)
.join('\n')
lines.push(
`module.exports = {`,
` onRouterTransitionStart: function (url, type) {`,
hookCalls,
` },`,
`};`
)
callback(null, lines.join('\n') + '\n')
})
.catch((err) => callback(err))
const resolvedModules = await Promise.all(
modules.map((spec) => resolve(rootContext, spec))
)
const allModules = [
...resolvedModules,
'private-next-instrumentation-client-user',
]
return `module.exports = [${allModules
.map((spec) => `require(${JSON.stringify(spec)})`)
.join(',')}];\n`
}
export default NextInstrumentationClientLoader
......@@ -27,6 +27,8 @@ import type { StaticIndicatorState } from './dev/hot-reloader/app/hot-reloader-a
import { createInitialRSCPayloadFromFallbackPrerender } from './flight-data-helpers'
import { getDeploymentId } from '../shared/lib/deployment-id'
import { setNavigationBuildId } from './navigation-build-id'
import type { ClientInstrumentationModules } from './router-transition-types'
import { initializeRouterTransitionModules } from './components/router-transition'
/// <reference types="react-dom/experimental" />
......@@ -339,15 +341,8 @@ const reactRootOptions: ReactDOMClient.RootOptions = {
onUncaughtError,
}
export type ClientInstrumentationHooks = {
onRouterTransitionStart?: (
url: string,
navigationType: 'push' | 'replace' | 'traverse'
) => void
}
export async function hydrate(
instrumentationHooks: ClientInstrumentationHooks | null,
instrumentationModules: ClientInstrumentationModules,
assetPrefix: string
) {
let staticIndicatorState: StaticIndicatorState | undefined
......@@ -376,6 +371,8 @@ export async function hydrate(
setNavigationBuildId(getDeploymentId()!)
}
initializeRouterTransitionModules(instrumentationModules)
const initialTimestamp = Date.now()
const actionQueue: AppRouterActionQueue = createMutableActionQueue(
createInitialRouterState({
......@@ -383,8 +380,7 @@ export async function hydrate(
initialRSCPayload,
initialFlightStreamForCache,
location: window.location,
}),
instrumentationHooks
})
)
const reactEl = (
......
......@@ -8,14 +8,14 @@ import { getOwnerStack } from '../next-devtools/userspace/app/errors/stitched-er
import { isRecoverableError } from './react-client-callbacks/on-recoverable-error'
// eslint-disable-next-line @next/internal/typechecked-require
const instrumentationHooks = require('../lib/require-instrumentation-client')
const instrumentationModules = require('../lib/require-instrumentation-client')
appBootstrap((assetPrefix) => {
const enableCacheIndicator = process.env.__NEXT_CACHE_COMPONENTS
const { hydrate } = require('./app-index') as typeof import('./app-index')
try {
hydrate(instrumentationHooks, assetPrefix)
hydrate(instrumentationModules, assetPrefix)
} finally {
renderAppDevOverlay(getOwnerStack, isRecoverableError, enableCacheIndicator)
}
......
......@@ -6,12 +6,12 @@ window.next.turbopack = true
;(self as any).__webpack_hash__ = ''
// eslint-disable-next-line @next/internal/typechecked-require
const instrumentationHooks = require('../lib/require-instrumentation-client')
const instrumentationModules = require('../lib/require-instrumentation-client')
appBootstrap((assetPrefix) => {
const { hydrate } = require('./app-index') as typeof import('./app-index')
try {
hydrate(instrumentationHooks, assetPrefix)
hydrate(instrumentationModules, assetPrefix)
} finally {
if (process.env.__NEXT_DEV_SERVER) {
const enableCacheIndicator = process.env.__NEXT_CACHE_COMPONENTS
......
......@@ -3,7 +3,7 @@
import './app-webpack'
import { appBootstrap } from './app-bootstrap'
const instrumentationHooks =
const instrumentationModules =
// eslint-disable-next-line @next/internal/typechecked-require -- not a module
require('../lib/require-instrumentation-client')
......@@ -14,5 +14,5 @@ appBootstrap((assetPrefix) => {
require('next/dist/client/components/app-router')
// eslint-disable-next-line @next/internal/typechecked-require -- Why not relative imports?
require('next/dist/client/components/layout-router')
hydrate(instrumentationHooks, assetPrefix)
hydrate(instrumentationModules, assetPrefix)
})
......@@ -35,9 +35,9 @@ import type {
PrefetchOptions,
} from '../../shared/lib/app-router-context.shared-runtime'
import { setLinkForCurrentNavigation, type LinkInstance } from './links'
import type { ClientInstrumentationHooks } from '../app-index'
import type { GlobalErrorComponent } from './builtin/global-error'
import { isJavaScriptURLString } from '../lib/javascript-url'
import { startRouterTransition } from './router-transition'
export type DispatchStatePromise = React.Dispatch<ReducerState>
......@@ -46,10 +46,6 @@ export type AppRouterActionQueue = {
dispatch: (payload: ReducerActions, setState: DispatchStatePromise) => void
action: (state: AppRouterState, action: ReducerActions) => ReducerState
onRouterTransitionStart:
| ((url: string, type: 'push' | 'replace' | 'traverse') => void)
| null
pending: ActionQueueNode | null
needsRefresh?: boolean
last: ActionQueueNode | null
......@@ -218,8 +214,7 @@ function dispatchAction(
let globalActionQueue: AppRouterActionQueue | null = null
export function createMutableActionQueue(
initialState: AppRouterState,
instrumentationHooks: ClientInstrumentationHooks | null
initialState: AppRouterState
): AppRouterActionQueue {
const actionQueue: AppRouterActionQueue = {
state: initialState,
......@@ -231,12 +226,6 @@ export function createMutableActionQueue(
},
pending: null,
last: null,
onRouterTransitionStart:
instrumentationHooks !== null &&
typeof instrumentationHooks.onRouterTransitionStart === 'function'
? // This profiling hook will be called at the start of every navigation.
instrumentationHooks.onRouterTransitionStart
: null,
}
if (typeof window !== 'undefined') {
......@@ -268,13 +257,6 @@ function getAppRouterActionQueue(): AppRouterActionQueue {
return globalActionQueue
}
function getProfilingHookForOnNavigationStart() {
if (globalActionQueue !== null) {
return globalActionQueue.onRouterTransitionStart
}
return null
}
export function dispatchNavigateAction(
href: string,
navigateType: NavigateAction['navigateType'],
......@@ -297,11 +279,7 @@ export function dispatchNavigateAction(
}
setLinkForCurrentNavigation(linkInstanceRef)
const onRouterTransitionStart = getProfilingHookForOnNavigationStart()
if (onRouterTransitionStart !== null) {
onRouterTransitionStart(href, navigateType)
}
startRouterTransition(href, navigateType)
dispatchAppRouterAction({
type: ACTION_NAVIGATE,
......@@ -317,10 +295,7 @@ export function dispatchTraverseAction(
href: string,
historyState: AppHistoryState | undefined
) {
const onRouterTransitionStart = getProfilingHookForOnNavigationStart()
if (onRouterTransitionStart !== null) {
onRouterTransitionStart(href, 'traverse')
}
startRouterTransition(href, 'traverse')
dispatchAppRouterAction({
type: ACTION_RESTORE,
url: new URL(href),
......
import type {
ClientInstrumentationHooks,
ClientInstrumentationModules,
RouterTransitionType,
} from '../router-transition-types'
let instrumentationModules: readonly ClientInstrumentationHooks[] = []
export function initializeRouterTransitionModules(
modules: ClientInstrumentationModules
): void {
instrumentationModules = modules.filter(
(module): module is ClientInstrumentationHooks => module != null
)
}
function callHooks(invoke: (hooks: ClientInstrumentationHooks) => void): void {
for (const hooks of instrumentationModules) {
try {
invoke(hooks)
} catch (error) {
console.error(
'An instrumentation-client router transition hook failed',
error
)
}
}
}
export function startRouterTransition(
url: string,
type: RouterTransitionType
): void {
callHooks((hooks) => hooks.onRouterTransitionStart?.(url, type))
}
export type RouterTransitionType = 'push' | 'replace' | 'traverse'
export type ClientInstrumentationHooks = {
onRouterTransitionStart?: (
url: string,
navigationType: RouterTransitionType
) => void
}
export type ClientInstrumentationModule =
| ClientInstrumentationHooks
| null
| undefined
export type ClientInstrumentationModules =
readonly ClientInstrumentationModule[]
/**
* This module imports the client instrumentation hook from the project root.
* This module imports the configured client instrumentation modules.
*
* The `private-next-instrumentation-client` module is automatically aliased to
* the `instrumentation-client.ts` file in the project root by webpack or turbopack.
* either the user's instrumentation module or a generated module array.
*/
if (process.env.NODE_ENV === 'development') {
const measureName = 'Client Instrumentation Hook'
const startTime = performance.now()
// eslint-disable-next-line @next/internal/typechecked-require -- Not a module.
module.exports = require('private-next-instrumentation-client')
const instrumentationClient = require('private-next-instrumentation-client')
module.exports = Array.isArray(instrumentationClient)
? instrumentationClient
: [instrumentationClient]
const endTime = performance.now()
const duration = endTime - startTime
......@@ -23,5 +26,8 @@ if (process.env.NODE_ENV === 'development') {
}
} else {
// eslint-disable-next-line @next/internal/typechecked-require -- Not a module.
module.exports = require('private-next-instrumentation-client')
const instrumentationClient = require('private-next-instrumentation-client')
module.exports = Array.isArray(instrumentationClient)
? instrumentationClient
: [instrumentationClient]
}
......@@ -2367,7 +2367,7 @@ function App<T>({
location: null,
})
const actionQueue = createMutableActionQueue(initialState, null)
const actionQueue = createMutableActionQueue(initialState)
const { HeadManagerContext } =
require('../../shared/lib/head-manager-context.shared-runtime') as typeof import('../../shared/lib/head-manager-context.shared-runtime')
......@@ -2428,7 +2428,7 @@ function ErrorApp<T>({
location: null,
})
const actionQueue = createMutableActionQueue(initialState, null)
const actionQueue = createMutableActionQueue(initialState)
return (
<ImageConfigContext.Provider value={images ?? imageConfigDefault}>
......
......@@ -5,4 +5,7 @@ window.__INJECT_A_EXECUTED_AT = performance.now()
export function onRouterTransitionStart(href, navigateType) {
const pathname = new URL(href, window.location.href).pathname
console.log(`[Router Transition Start] [${navigateType}] ${pathname} a`)
if (window.__THROW_INJECT_A) {
throw new Error('inject a transition hook failed')
}
}
window.__INJECT_ORDER = window.__INJECT_ORDER || []
window.__INJECT_ORDER.push('late-hook')
const hooks = {}
module.exports = hooks
window.__INSTALL_LATE_INSTRUMENTATION_HOOK = () => {
hooks.onRouterTransitionStart = (href, navigateType) => {
const pathname = new URL(href, window.location.href).pathname
console.log(
`[Router Transition Start] [${navigateType}] ${pathname} late-hook`
)
}
}
window.__INJECT_ORDER = window.__INJECT_ORDER || []
window.__INJECT_ORDER.push('side-effect')
module.exports = null
/** @type {import('next').NextConfig} */
export default {
instrumentationClientInject: ['./inject-a.js', './inject-b.js'],
instrumentationClientInject: [
'./inject-side-effect.cjs',
'./inject-late-hook.cjs',
'./inject-a.js',
'./inject-b.js',
],
}
......@@ -115,31 +115,32 @@ describe('Instrumentation Client Hook', () => {
packageJson,
})
it('runs each injected entry before the user instrumentation-client and before hydration, in array order', async () => {
it('runs each injected module before the user instrumentation-client and before hydration, in array order', async () => {
const browser = await next.browser('/')
const order = await browser.eval(`window.__INJECT_ORDER`)
expect(order).toEqual(['a', 'b', 'user'])
expect(order).toEqual(['side-effect', 'late-hook', 'a', 'b', 'user'])
const injectA = await browser.eval(`window.__INJECT_A_EXECUTED_AT`)
const injectB = await browser.eval(`window.__INJECT_B_EXECUTED_AT`)
const moduleA = await browser.eval(`window.__INJECT_A_EXECUTED_AT`)
const moduleB = await browser.eval(`window.__INJECT_B_EXECUTED_AT`)
const userTime = await browser.eval(
`window.__INSTRUMENTATION_CLIENT_EXECUTED_AT`
)
const hydrationTime = await browser.eval(`window.__NEXT_HYDRATED_AT`)
expect(injectA).toBeDefined()
expect(injectB).toBeDefined()
expect(moduleA).toBeDefined()
expect(moduleB).toBeDefined()
expect(userTime).toBeDefined()
expect(hydrationTime).toBeDefined()
expect(injectA).toBeLessThanOrEqual(injectB)
expect(injectB).toBeLessThanOrEqual(userTime)
expect(moduleA).toBeLessThanOrEqual(moduleB)
expect(moduleB).toBeLessThanOrEqual(userTime)
expect(userTime).toBeLessThan(hydrationTime)
})
it('still surfaces onRouterTransitionStart from the user instrumentation-client when injects are configured', async () => {
it('surfaces onRouterTransitionStart from every injected module', async () => {
const browser = await next.browser('/')
await browser.eval(`window.__INSTALL_LATE_INSTRUMENTATION_HOOK()`)
const linkToSomePage = await browser.elementByCss('a[href="/some-page"]')
await linkToSomePage.click()
......@@ -150,14 +151,40 @@ describe('Instrumentation Client Hook', () => {
await browser.elementById('home')
expect(filterNavigationStartLogs(await browser.log())).toEqual([
'[Router Transition Start] [push] /some-page late-hook',
'[Router Transition Start] [push] /some-page a',
'[Router Transition Start] [push] /some-page b',
'[Router Transition Start] [push] /some-page user',
'[Router Transition Start] [push] / late-hook',
'[Router Transition Start] [push] / a',
'[Router Transition Start] [push] / b',
'[Router Transition Start] [push] / user',
])
})
it('isolates hook errors between injected modules', async () => {
const browser = await next.browser('/')
await browser.eval(`window.__INSTALL_LATE_INSTRUMENTATION_HOOK()`)
await browser.eval(`window.__THROW_INJECT_A = true`)
await browser.elementByCss('a[href="/some-page"]').click()
await browser.elementById('some-page')
const logs = await browser.log()
expect(filterNavigationStartLogs(logs)).toEqual([
'[Router Transition Start] [push] /some-page late-hook',
'[Router Transition Start] [push] /some-page a',
'[Router Transition Start] [push] /some-page b',
'[Router Transition Start] [push] /some-page user',
])
expect(
logs.filter((log) =>
log.message.includes(
'An instrumentation-client router transition hook failed'
)
)
).toHaveLength(1)
})
})
if (isNextDev) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment