feat(instrumentation): support nextConfig.instrumentationClientInject

packages/vinext/src/client/instrumentation-client-inject.ts

@@ -0,0 +1,60 @@
+/**
+ * Generate a virtual ESM module that implements the Next.js
+ * `instrumentationClientInject` contract for client bootstrap.
+ *
+ * Resolution follows two paths depending on whether injects are configured:
+ *
+ * **Empty injects (`injects.length === 0`):** Returns `export {}` and the
+ * plugin does not serve a virtual module. The `resolve.alias` for
+ * `private-next-instrumentation-client` resolves directly to the user's
+ * `instrumentation-client` file (or `vinext/client/empty-module` when absent),
+ * so the user's `onRouterTransitionStart` is used as-is with no composition.
+ *
+ * **Non-empty injects:** The plugin serves this generated module via
+ * `resolveId`/`load`. It side-effect-imports each inject in config order, then
+ * the user's file last, and exports a single composed `onRouterTransitionStart`
+ * that fans out to every module's hook.
+ *
+ * @param injects - Module specifiers from `nextConfig.instrumentationClientInject`
+ * @param userPath - Absolute path to the user's `instrumentation-client` file,
+ *                   or `null` when the file doesn't exist
+ */
+export function generateInstrumentationClientInjectModule(
+  injects: readonly string[],
+  userPath: string | null,
+): string {
+  const EMPTY_MODULE = "vinext/client/empty-module";
+
+  // No injects: Next.js keeps the current transparent passthrough.
+  // The alias already handles the user file or empty-module, so emit
+  // nothing that could shadow what the alias resolves.
+  if (injects.length === 0) {
+    return "export {};";
+  }
+
+  const lines: string[] = [];
+
+  for (let i = 0; i < injects.length; i++) {
+    lines.push(`import * as __vinj_${i} from ${JSON.stringify(injects[i])};`);
+  }
+
+  const lastIndex = injects.length;
+  lines.push(`import * as __vinj_${lastIndex} from ${JSON.stringify(userPath ?? EMPTY_MODULE)};`);
+
+  const hookCalls: string[] = [];
+  for (let i = 0; i <= lastIndex; i++) {
+    hookCalls.push(
+      `  if (typeof __vinj_${i}.onRouterTransitionStart === "function") {`,
+      `    __vinj_${i}.onRouterTransitionStart(url, type);`,
+      `  }`,
+    );
+  }
+
+  lines.push("");
+  lines.push("export function onRouterTransitionStart(url: string, type: string) {");
+  lines.push(...hookCalls);
+  lines.push(`}`);
+  lines.push("");
+
+  return lines.join("\n");
+}

packages/vinext/src/config/next-config.ts

@@ -211,6 +211,12 @@ export type NextConfig = {
   output?: "export" | "standalone";
   /** File extensions treated as routable pages/routes (Next.js pageExtensions) */
   pageExtensions?: string[];
+  /**
+   * Module specifiers that are required for side effects on the client before
+   * hydration, in array order, ahead of the user's `instrumentation-client.{ts,js}`.
+   * Each entry may be a bare npm package name or a path relative to the project root.
+   */
+  instrumentationClientInject?: string[];
   /** Extra origins allowed to access the dev server. */
   allowedDevOrigins?: string[];
   /** Maximum age in seconds for stale ISR entries before blocking regeneration. */
@@ -290,6 +296,7 @@ export type ResolvedNextConfig = {
   trailingSlash: boolean;
   output: "" | "export" | "standalone";
   pageExtensions: string[];
+  instrumentationClientInject: string[];
   cacheComponents: boolean;
   redirects: NextRedirect[];
   rewrites: {
@@ -951,6 +958,7 @@ export async function resolveNextConfig(
       buildId,
       deploymentId,
       sassOptions: null,
+      instrumentationClientInject: [],
     };
     detectNextIntlConfig(root, resolved);
     return resolved;
@@ -1138,6 +1146,11 @@ export async function resolveNextConfig(
     trailingSlash: config.trailingSlash ?? false,
     output: output === "export" || output === "standalone" ? output : "",
     pageExtensions,
+    instrumentationClientInject: Array.isArray(config.instrumentationClientInject)
+      ? (config.instrumentationClientInject as unknown[]).filter(
+          (x): x is string => typeof x === "string",
+        )
+      : [],
     cacheComponents: config.cacheComponents ?? false,
     redirects,
     rewrites,

packages/vinext/src/index.ts

@@ -93,6 +93,7 @@ import { clientReferenceDedupPlugin } from "./plugins/client-reference-dedup.js"
 import { dataUrlCssPlugin } from "./plugins/css-data-url.js";
 import { createRscClientReferenceLoadersPlugin } from "./plugins/rsc-client-reference-loaders.js";
 import { createInstrumentationClientTransformPlugin } from "./plugins/instrumentation-client.js";
+import { generateInstrumentationClientInjectModule } from "./client/instrumentation-client-inject.js";
 import { createMiddlewareServerOnlyPlugin } from "./plugins/middleware-server-only.js";
 import { createOptimizeImportsPlugin } from "./plugins/optimize-imports.js";
 import { createOgInlineFetchAssetsPlugin, ogAssetsPlugin } from "./plugins/og-assets.js";
@@ -438,6 +439,9 @@ const VIRTUAL_APP_BROWSER_ENTRY = "virtual:vinext-app-browser-entry";
 const RESOLVED_APP_BROWSER_ENTRY = "\0" + VIRTUAL_APP_BROWSER_ENTRY;
 const VIRTUAL_ROOT_PARAMS = "virtual:vinext-root-params";
 const RESOLVED_ROOT_PARAMS = "\0" + VIRTUAL_ROOT_PARAMS;
+/** Virtual module for composed instrumentation-client bootstrap. */
+const VIRTUAL_INSTRUMENTATION_CLIENT = "private-next-instrumentation-client";
+const RESOLVED_INSTRUMENTATION_CLIENT = "\0" + VIRTUAL_INSTRUMENTATION_CLIENT;
 /** Image file extensions handled by the vinext:image-imports plugin.
  *  Shared between the Rolldown hook filter and the transform handler regex. */
 const IMAGE_EXTS = "png|jpe?g|gif|webp|avif|svg|ico|bmp|tiff?";
@@ -654,6 +658,7 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
   let middlewarePath: string | null = null;
   let instrumentationPath: string | null = null;
   let instrumentationClientPath: string | null = null;
+  let clientInjectModule: string | null = null;
   let hasCloudflarePlugin = false;
   let warnedInlineNextConfigOverride = false;
   let hasNitroPlugin = false;
@@ -1072,6 +1077,13 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
         instrumentationPath = findInstrumentationFile(root, fileMatcher);
         instrumentationClientPath = findInstrumentationClientFile(root, fileMatcher);
         middlewarePath = findMiddlewareFile(root, fileMatcher);
+        clientInjectModule =
+          nextConfig.instrumentationClientInject.length > 0
+            ? generateInstrumentationClientInjectModule(
+                nextConfig.instrumentationClientInject,
+                instrumentationClientPath,
+              )
+            : null;
         if (env?.command === "build") {
           await writeRouteTypes();
         }
@@ -2321,6 +2333,28 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
     // Stub node:async_hooks in client builds — see src/plugins/async-hooks-stub.ts
     asyncHooksStubPlugin,
     createInstrumentationClientTransformPlugin(() => instrumentationClientPath),
+    // Generate a virtual `private-next-instrumentation-client` module when
+    // `nextConfig.instrumentationClientInject` is non-empty. Side-effect imports
+    // run in array order, ending with the user's `instrumentation-client` file
+    // (or empty-module), and a single composed `onRouterTransitionStart` fans
+    // out to every module's hook.
+    {
+      name: "vinext:instrumentation-client-inject",
+      enforce: "pre",
+
+      resolveId(id) {
+        if (id !== VIRTUAL_INSTRUMENTATION_CLIENT) return null;
+        // The module was generated in config() if there are injects to compose.
+        // When empty, resolve.alias handles passthrough to the user file or empty-module.
+        return clientInjectModule !== null ? RESOLVED_INSTRUMENTATION_CLIENT : null;
+      },
+
+      load(id) {
+        if (id !== RESOLVED_INSTRUMENTATION_CLIENT) return null;
+        // Deterministic output precomputed once in config().
+        return clientInjectModule;
+      },
+    },
     // Dedup client references from RSC proxy modules — see src/plugins/client-reference-dedup.ts
     ...(options.experimental?.clientReferenceDedup ? [clientReferenceDedupPlugin()] : []),
     // Proxy plugin for @mdx-js/rollup. The real MDX plugin is created lazily

tests/instrumentation.test.ts

@@ -6,6 +6,7 @@ import {
   findInstrumentationClientFile,
   findInstrumentationFile,
 } from "../packages/vinext/src/server/instrumentation.js";
+import { generateInstrumentationClientInjectModule } from "../packages/vinext/src/client/instrumentation-client-inject.js";
 import { createValidFileMatcher } from "../packages/vinext/src/routing/file-matcher.js";
 
 // The runInstrumentation/reportRequestError describe blocks re-import via
@@ -342,3 +343,60 @@ describe("reportRequestError", () => {
     expect(onRequestError).toHaveBeenCalledOnce();
   });
 });
+
+describe("generateInstrumentationClientInjectModule", () => {
+  it("returns passthrough when injects is empty", () => {
+    const code = generateInstrumentationClientInjectModule([], null);
+    expect(code).toBe("export {};");
+  });
+
+  it("generates a single import for one inject entry", () => {
+    const code = generateInstrumentationClientInjectModule(["./inject-a.js"], null);
+    expect(code).toContain('import * as __vinj_0 from "./inject-a.js"');
+    expect(code).toContain("export function onRouterTransitionStart(url: string, type: string)");
+    expect(code).toContain('typeof __vinj_0.onRouterTransitionStart === "function"');
+    expect(code).toContain("\n    __vinj_0.onRouterTransitionStart(url, type);\n");
+  });
+
+  it("generates imports in config order with user file last", () => {
+    const code = generateInstrumentationClientInjectModule(
+      ["./inject-a.js", "some-npm-pkg"],
+      "/project/instrumentation-client.ts",
+    );
+    expect(code).toContain('import * as __vinj_0 from "./inject-a.js"');
+    expect(code).toContain('import * as __vinj_1 from "some-npm-pkg"');
+    expect(code).toContain('import * as __vinj_2 from "/project/instrumentation-client.ts"');
+  });
+
+  it("falls back to empty-module when user file is absent", () => {
+    const code = generateInstrumentationClientInjectModule(["./inject-a.js"], null);
+    expect(code).toContain('import * as __vinj_1 from "vinext/client/empty-module"');
+  });
+
+  it("composes hook calls for every module in array order", () => {
+    const code = generateInstrumentationClientInjectModule(
+      ["./inject-a.js", "./inject-b.js"],
+      "/project/instrumentation-client.ts",
+    );
+    // Each module should have its own hook-check-and-call
+    expect(code).toContain('typeof __vinj_0.onRouterTransitionStart === "function"');
+    expect(code).toContain("__vinj_0.onRouterTransitionStart(url, type)");
+    expect(code).toContain('typeof __vinj_1.onRouterTransitionStart === "function"');
+    expect(code).toContain("__vinj_1.onRouterTransitionStart(url, type)");
+    expect(code).toContain('typeof __vinj_2.onRouterTransitionStart === "function"');
+    expect(code).toContain("__vinj_2.onRouterTransitionStart(url, type)");
+  });
+
+  it("exports empty object when injects is empty and user file is present", () => {
+    const code = generateInstrumentationClientInjectModule(
+      [],
+      "/project/instrumentation-client.ts",
+    );
+    expect(code).toBe("export {};");
+  });
+
+  it("escapes special characters in specifier paths", () => {
+    const code = generateInstrumentationClientInjectModule(['./path/with"quote.js'], null);
+    expect(code).toContain('from "./path/with\\"quote.js"');
+  });
+});

tests/next-config.test.ts

@@ -925,6 +925,7 @@ describe("detectNextIntlConfig", () => {
       buildId: "test-build-id",
       deploymentId: undefined,
       sassOptions: null,
+      instrumentationClientInject: [],
       ...overrides,
     };
   }