fix(v10/server-utils): Stop shipping orchestrion bundler plugins as production dependencies (#23667)

Backport of: #22443

Closes: #23611

`@sentry/server-utils` shipped the orchestrion bundler plugins and a
full JavaScript parser toolchain (meriyah, esquery, astring, source-map)
as production dependencies, so every consumer of `@sentry/node`
installed roughly 5 MB of code that no runtime path reaches unless they
opt into diagnostics-channel injection. The orchestrion runtime chain is
now compiled into this package's own build, and all `@apm-js-collab/*`
packages plus meriyah become devDependencies. Production dependencies
are down to `@sentry/conventions` and `@sentry/core`.

## Differences to the original PR

- `packages/server-utils/src/orchestrion/runtime/register.ts`: kept
`RegisterDiagnosticsChannelInjectionOptions` and the optional parameter
on `registerDiagnosticsChannelInjection()`, now deprecated and ignored.
The original deletes both; on v10 the option is reachable through the
public `experimentalUseDiagnosticsChannelInjection(options)`, so
removing it would be a compile error for anyone passing
`tracingHooksDir`.
- `packages/node/src/sdk/experimentalUseDiagnosticsChannelInjection.ts`:
same reason, the optional parameter stays.
- `packages/server-utils/src/orchestrion/runtime/register.ts`: kept
v10's loader-thread guard (`isMainThread` / `parentPort`), which landed
after the v10 branch point and is not in the original.
-
`packages/nextjs/src/config/withSentryConfig/getFinalConfigObjectUtils.ts`
and `getFinalConfigObject.ts`: removed
`maybeAddOutputFileTracingIncludes` plus its tests in
`packages/nextjs/test/config/withSentryConfig.test.ts`. That
`@vercel/nft` force-include is a v10-only workaround for meriyah's
`module-sync` exports map (#23034), which bundling removes. `develop`
never carried it, so this brings both branches to the same state.

---------

Co-authored-by: Tim Fish <tim@timfish.uk>

Author: andreiborza

.size-limit.js

@@ -400,12 +400,12 @@ module.exports = [
     import: createImport('init', 'experimentalUseDiagnosticsChannelInjection'),
     ignore: [...builtinModules, ...nodePrefixedBuiltinModules],
     gzip: true,
-    limit: '154 KB',
+    limit: '190 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
     name: '@sentry/node/import (ESM hook with diagnostics-channel injection)',
-    path: ['node_modules/@apm-js-collab/tracing-hooks/hook.mjs', 'packages/node/build/import-hook.mjs'],
+    path: ['packages/server-utils/build/esm/orchestrion/runtime/hook.js', 'packages/node/build/import-hook.mjs'],
     ignore: [...builtinModules, ...nodePrefixedBuiltinModules],
     gzip: true,
     limit: '76 KB',

dev-packages/e2e-tests/test-applications/nextjs-16-standalone/tests/standalone.test.ts

@@ -1,32 +1,6 @@
-import * as fs from 'fs';
-import * as path from 'path';
 import { expect, test } from '@playwright/test';
 import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
-function findFileInDir(dir: string, suffix: string): string | undefined {
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const entryPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      const found = findFileInDir(entryPath, suffix);
-      if (found) {
-        return found;
-      }
-    } else if (entryPath.endsWith(suffix)) {
-      return entryPath;
-    }
-  }
-  return undefined;
-}
-
-test('standalone output contains all meriyah files needed at runtime', () => {
-  // meriyah's ESM build sits behind the `module-sync` export condition, which Next.js' output file
-  // tracing resolves differently than the Node.js runtime does (https://github.com/vercel/nft/issues/603).
-  // Without the SDK force-including it, the standalone server crashes with ERR_MODULE_NOT_FOUND.
-  const standaloneDir = path.join(process.cwd(), '.next', 'standalone');
-  expect(findFileInDir(standaloneDir, path.join('meriyah', 'dist', 'meriyah.mjs'))).toBeDefined();
-  expect(findFileInDir(standaloneDir, path.join('meriyah', 'dist', 'meriyah.cjs'))).toBeDefined();
-});
-
 test('sends a server transaction from the standalone server', async ({ page }) => {
   const transactionPromise = waitForTransaction('nextjs-16-standalone', transactionEvent => {
     return transactionEvent.transaction === 'GET /';

dev-packages/e2e-tests/test-applications/nuxt-3-min/package.json

@@ -27,8 +27,7 @@
   },
   "pnpm": {
     "overrides": {
-      "ofetch": "1.4.0",
-      "@vercel/nft": "0.29.4"
+      "ofetch": "1.4.0"
     }
   },
   "volta": {

packages/nextjs/src/config/diagnosticsChannelInjection.ts

@@ -1,3 +1,5 @@
+import { resolveOrchestrionRuntimeRequest } from '@sentry/server-utils/orchestrion/webpack';
+
 /**
  * Instrumented packages verified (via e2e) to bundle correctly, removed from Sentry's own
  * `serverExternalPackages` defaults so the build-time loader can transform them. Everything else
@@ -7,16 +9,55 @@
 export const BUNDLE_SAFE_INSTRUMENTED_PACKAGES = ['ioredis'];
 
 /**
- * The orchestrion runtime machinery must stay external — its parser breaks when bundled, which
- * silently disables the runtime module hook.
+ * `@sentry/server-utils` (where `register.ts` and the bundled orchestrion runtime ship) must stay
+ * external: `register.ts` passes its own `__filename`/`import.meta.url` as the `parentURL` for
+ * `Module.register('@sentry/server-utils/orchestrion/hook.mjs', …)`, so that self-reference only
+ * resolves while the code still lives at its real `node_modules` location. Bundled into an app
+ * server chunk instead, the specifier would have to resolve from the chunk's output location,
+ * which fails under isolated installs (pnpm) where the package is a transitive dependency.
+ *
+ * (The `@apm-js-collab/*` packages no longer appear here: they are bundled into
+ * `@sentry/server-utils`' build, so no import of them exists at runtime.)
  */
-export const ORCHESTRION_RUNTIME_EXTERNAL_PACKAGES = [
-  '@apm-js-collab/tracing-hooks',
-  '@apm-js-collab/code-transformer',
-];
+export const ORCHESTRION_RUNTIME_EXTERNAL_PACKAGES = ['@sentry/server-utils'];
 
 /** Remove the given packages from a `serverExternalPackages` list. */
 export function filterInstrumentedExternals(externals: string[], packagesToBundle: string[]): string[] {
   const set = new Set(packagesToBundle);
   return externals.filter(name => !set.has(name));
 }
+
+/**
+ * A webpack `externals` array entry that keeps {@link ORCHESTRION_RUNTIME_EXTERNAL_PACKAGES} truly
+ * external by resolving each request to an absolute path at build time and emitting a
+ * `commonjs <absolute path>` external.
+ *
+ * Listing the packages in `serverExternalPackages` is not enough: Next.js only externalizes a
+ * package when its bare specifier also resolves from the project root (`resolveExternal`'s
+ * base-resolve check in `next/dist/build/handle-externals.js`) — otherwise the
+ * `require('<bare specifier>')` it emits into the chunk would dangle at runtime, so Next silently
+ * bundles the package instead. Under isolated installs (pnpm) the package is a transitive
+ * dependency that never resolves from the project root, so the orchestrion runtime ended up
+ * compiled into the server chunk — breaking the `Module.register` self-reference described on
+ * {@link ORCHESTRION_RUNTIME_EXTERNAL_PACKAGES}. Absolute paths sidestep all of this — webpack
+ * emits `require('/abs/path/…')`, which loads the real files from `node_modules` no matter where
+ * the chunk lives.
+ *
+ * Must be placed *before* Next's own externals handler in the `externals` array: webpack calls
+ * array entries in order and stops at the first one that returns a result.
+ */
+export async function externalizeOrchestrionRuntimePackages({
+  request,
+}: {
+  request?: string;
+}): Promise<string | undefined> {
+  if (
+    !request ||
+    !ORCHESTRION_RUNTIME_EXTERNAL_PACKAGES.some(pkg => request === pkg || request.startsWith(`${pkg}/`))
+  ) {
+    return undefined;
+  }
+
+  const resolved = resolveOrchestrionRuntimeRequest(request);
+  return resolved ? `commonjs ${resolved}` : undefined;
+}

packages/nextjs/src/config/webpack.ts

@@ -6,6 +6,7 @@ import * as fs from 'fs';
 import { createRequire } from 'module';
 import * as path from 'path';
 import type { VercelCronsConfig } from '../common/types';
+import { externalizeOrchestrionRuntimePackages } from './diagnosticsChannelInjection';
 import { getBuildPluginOptions, normalizePathForGlob } from './getBuildPluginOptions';
 import type { RouteManifest } from './manifest/types';
 // Note: If you need to import a type from Webpack, do it in `types.ts` and export it from there. Otherwise, our
@@ -434,6 +435,7 @@ export function constructWebpackConfigFunction({
     // Orchestrion code-transform loader — Node server runtime only, never the edge compilation
     if (runtime === 'server' && userSentryOptions._experimental?.useDiagnosticsChannelInjection) {
       newConfig.plugins.push(sentryOrchestrionWebpackPlugin() as unknown as WebpackPluginInstance);
+      prependOrchestrionRuntimeExternals(newConfig);
     }
 
     return newConfig;
@@ -872,6 +874,23 @@ function addOtelWarningIgnoreRule(newConfig: WebpackConfigObjectWithModuleRules)
   }
 }
 
+/**
+ * Prepends {@link externalizeOrchestrionRuntimePackages} to `newConfig.externals`, ahead of
+ * Next.js's own externals handler, so the orchestrion runtime packages stay external even where
+ * `serverExternalPackages` can't keep them so. See that function's docs for why this is necessary.
+ */
+function prependOrchestrionRuntimeExternals(newConfig: WebpackConfigObjectWithModuleRules): void {
+  const existingExternals = newConfig.externals;
+
+  if (Array.isArray(existingExternals)) {
+    existingExternals.unshift(externalizeOrchestrionRuntimePackages);
+  } else if (existingExternals === undefined) {
+    newConfig.externals = [externalizeOrchestrionRuntimePackages];
+  } else {
+    newConfig.externals = [externalizeOrchestrionRuntimePackages, existingExternals];
+  }
+}
+
 function addEdgeRuntimePolyfills(newConfig: WebpackConfigObjectWithModuleRules, buildContext: BuildContext): void {
   // Use ProvidePlugin to inject performance global only when accessed
   newConfig.plugins = newConfig.plugins || [];

packages/nextjs/src/config/withSentryConfig/buildTime.ts

@@ -1,7 +1,6 @@
 import * as childProcess from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import { getTracingHooksDirectory } from '@sentry/server-utils/orchestrion/webpack';
 import type { NextConfigObject, SentryBuildOptions } from '../types';
 
 /**
@@ -54,9 +53,6 @@ export function setUpBuildTimeVariables(
   // Marker read by the server SDK to warn if the runtime opt-in call is missing.
   if (userSentryOptions._experimental?.useDiagnosticsChannelInjection) {
     buildTimeVariables._sentryUseDiagnosticsChannelInjection = 'true';
-    // Resolved here (where the SDK is a real on-disk package) and inlined, because the runtime
-    // module hook can't resolve the bare specifier from a bundled server chunk under pnpm.
-    buildTimeVariables._sentryOrchestrionTracingHooksDir = getTracingHooksDirectory();
   }
 
   if (basePath) {

packages/nextjs/src/config/withSentryConfig/getFinalConfigObject.ts

@@ -16,7 +16,6 @@ import {
 } from './getFinalConfigObjectBundlerUtils';
 import {
   getNextMajor,
-  maybeAddOutputFileTracingIncludes,
   maybeCreateRouteManifest,
   maybeGetVercelCronsConfig,
   maybeSetClientTraceMetadataOption,
@@ -54,7 +53,6 @@ export function getFinalConfigObject(
 
   maybeSetClientTraceMetadataOption(incomingUserNextConfigObject, nextJsVersion);
   maybeSetInstrumentationHookOption(incomingUserNextConfigObject, nextJsVersion);
-  maybeAddOutputFileTracingIncludes(incomingUserNextConfigObject, nextJsVersion);
   warnIfMissingOnRouterTransitionStartHook(userSentryOptions);
 
   const bundlerInfo = getBundlerInfo(nextJsVersion);

packages/nextjs/src/config/withSentryConfig/getFinalConfigObjectUtils.ts

@@ -1,7 +1,6 @@
 import { debug, isMatchingPattern, parseSemver } from '@sentry/core';
 import { getSentryRelease } from '@sentry/node';
 import * as fs from 'fs';
-import { createRequire } from 'module';
 import * as path from 'path';
 import type { VercelCronsConfig } from '../../common/types';
 import { createRouteManifest } from '../manifest/createRouteManifest';
@@ -262,72 +261,6 @@ export function getNextMajor(nextJsVersion: string | undefined): number | undefi
   return major;
 }
 
-/**
- * Forces `meriyah`'s runtime files into Next.js' output file tracing.
- *
- * `meriyah` (a runtime dependency of `@sentry/server-utils`) declares its ESM build behind the
- * `module-sync` export condition. Whether `@vercel/nft` traces that condition's target depends on
- * the Node.js version running the build and on the nft version the installed Next.js bundles, so
- * the traced file set can miss the file Node actually resolves at runtime. `output: 'standalone'`
- * builds (and Vercel deployments) then crash on boot with `ERR_MODULE_NOT_FOUND` for
- * `meriyah/dist/meriyah.mjs`. Force-including both build outputs makes the trace independent of
- * the build environment. (https://github.com/vercel/nft/issues/603,
- * https://github.com/getsentry/sentry-javascript/issues/23034)
- *
- * Only applied on Next.js >= 14.1: before that, `collectBuildTraces` receives
- * `Object.entries(pageInfos)` of a `Map` (i.e. an empty array), so its "edge routes have no trace
- * files" guard never matches and any include glob matching a pages-router edge route crashes the
- * build with ENOENT on the route's missing `.nft.json` (fixed by
- * https://github.com/vercel/next.js/pull/59157, released in 14.1.0).
- *
- * Note: this mutates `incomingUserNextConfigObject`.
- */
-export function maybeAddOutputFileTracingIncludes(
-  incomingUserNextConfigObject: NextConfigObject,
-  nextJsVersion: string | undefined,
-): void {
-  if (!nextJsVersion) {
-    return;
-  }
-
-  const { major, minor } = parseSemver(nextJsVersion);
-  if (major === undefined || minor === undefined || major < 14 || (major === 14 && minor < 1)) {
-    return;
-  }
-
-  let meriyahDistDir: string;
-  try {
-    // Resolve through the dependency chain (@sentry/nextjs -> @sentry/server-utils -> meriyah) so
-    // the resolved copy is the one the runtime hook actually loads, even with strict pnpm layouts.
-    const serverUtilsPkgPath = createRequire(`${__dirname}/`).resolve('@sentry/server-utils/package.json');
-    meriyahDistDir = path.dirname(createRequire(serverUtilsPkgPath).resolve('meriyah'));
-  } catch {
-    return;
-  }
-
-  // Include globs are resolved relative to the project directory; normalize to posix separators
-  // since both the glob matching and Turbopack's native implementation expect forward slashes.
-  const meriyahIncludes = ['meriyah.mjs', 'meriyah.cjs'].map(file =>
-    path.relative(process.cwd(), path.join(meriyahDistDir, file)).replace(/\\/g, '/'),
-  );
-
-  const mergeIncludes = (existing: Record<string, string[]> | undefined): Record<string, string[]> => ({
-    ...existing,
-    '/*': [...new Set([...(existing?.['/*'] ?? []), ...meriyahIncludes])],
-  });
-
-  if (major >= 15) {
-    incomingUserNextConfigObject.outputFileTracingIncludes = mergeIncludes(
-      incomingUserNextConfigObject.outputFileTracingIncludes,
-    );
-  } else {
-    incomingUserNextConfigObject.experimental = {
-      ...incomingUserNextConfigObject.experimental,
-      outputFileTracingIncludes: mergeIncludes(incomingUserNextConfigObject.experimental?.outputFileTracingIncludes),
-    };
-  }
-}
-
 /**
  * Reads the Vercel crons configuration from vercel.json.
  * Returns undefined if vercel.json doesn't exist or doesn't contain crons.

packages/nextjs/src/server/index.ts

@@ -48,23 +48,15 @@ const globalWithInjectedValues = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
   _sentryRewriteFramesDistDir?: string;
   _sentryRelease?: string;
   _sentryUseDiagnosticsChannelInjection?: string;
-  _sentryOrchestrionTracingHooksDir?: string;
 };
 
 /**
  * EXPERIMENTAL: Next.js-aware variant of `Sentry.experimentalUseDiagnosticsChannelInjection()`
  * from `@sentry/node` (see its docs for behavior and caveats).
- *
- * Next.js bundles the SDK into the server build, from where the runtime module hook can't resolve
- * the `@apm-js-collab/tracing-hooks` bare specifier under isolated installs (pnpm). This variant
- * points the hook at the package location that `withSentryConfig` resolved at build time.
- *
  * @experimental May change or be removed in any release.
  */
 export function experimentalUseDiagnosticsChannelInjection(): void {
-  const tracingHooksDir =
-    process.env._sentryOrchestrionTracingHooksDir || globalWithInjectedValues._sentryOrchestrionTracingHooksDir;
-  nodeExperimentalUseDiagnosticsChannelInjection(tracingHooksDir ? { tracingHooksDir } : undefined);
+  nodeExperimentalUseDiagnosticsChannelInjection();
 }
 
 // Call at module level so `next build` prerender workers still register the runner without `init`

packages/nextjs/test/config/diagnosticsChannelInjection.test.ts

@@ -1,6 +1,9 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import {
   BUNDLE_SAFE_INSTRUMENTED_PACKAGES,
+  externalizeOrchestrionRuntimePackages,
   filterInstrumentedExternals,
 } from '../../src/config/diagnosticsChannelInjection';
 import { setUpBuildTimeVariables } from '../../src/config/withSentryConfig/buildTime';
@@ -33,8 +36,7 @@ describe('getServerExternalPackagesPatch (diagnostics-channel injection)', () =>
     expect(externals).toContain('pg');
     expect(externals).toContain('pg-pool');
     // The orchestrion machinery must be external for the runtime hook to work.
-    expect(externals).toContain('@apm-js-collab/tracing-hooks');
-    expect(externals).toContain('@apm-js-collab/code-transformer');
+    expect(externals).toContain('@sentry/server-utils');
   });
 
   it('respects user-provided externals even for bundle-safe packages', () => {
@@ -51,15 +53,50 @@ describe('getServerExternalPackagesPatch (diagnostics-channel injection)', () =>
   });
 });
 
+describe('externalizeOrchestrionRuntimePackages', () => {
+  it.each(['@sentry/server-utils', '@sentry/server-utils/orchestrion', '@sentry/server-utils/orchestrion/register'])(
+    'externalizes %s as an absolute-path commonjs require',
+    async request => {
+      const external = await externalizeOrchestrionRuntimePackages({ request });
+
+      expect(external).toMatch(/^commonjs /);
+      const resolvedPath = external!.slice('commonjs '.length);
+      expect(isAbsolute(resolvedPath)).toBe(true);
+      expect(existsSync(resolvedPath)).toBe(true);
+    },
+  );
+
+  it('ignores the bundled @apm-js-collab packages — no import of them exists in the dist anymore', async () => {
+    await expect(
+      externalizeOrchestrionRuntimePackages({ request: '@apm-js-collab/tracing-hooks' }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('resolves @sentry/server-utils subpaths to the CJS build, since the emitted external is a require()', async () => {
+    const external = await externalizeOrchestrionRuntimePackages({
+      request: '@sentry/server-utils/orchestrion/register',
+    });
+
+    expect(external).toMatch(/[/\\]cjs[/\\]/);
+  });
+
+  it('ignores unrelated requests so later externals handlers still run', async () => {
+    await expect(externalizeOrchestrionRuntimePackages({ request: 'some-other-package' })).resolves.toBeUndefined();
+    // Prefix matching must not leak beyond a package-name boundary.
+    await expect(
+      externalizeOrchestrionRuntimePackages({ request: '@sentry/server-utils-extras' }),
+    ).resolves.toBeUndefined();
+    await expect(externalizeOrchestrionRuntimePackages({})).resolves.toBeUndefined();
+  });
+});
+
 describe('setUpBuildTimeVariables (diagnostics-channel injection)', () => {
   it('injects the flag marker and the tracing-hooks location', () => {
     const nextConfig: NextConfigObject = {};
     setUpBuildTimeVariables(nextConfig, { _experimental: { useDiagnosticsChannelInjection: true } }, undefined);
 
     expect(nextConfig.env).toMatchObject({
       _sentryUseDiagnosticsChannelInjection: 'true',
-      // The runtime module hook joins subpaths onto this, so it must be an absolute directory.
-      _sentryOrchestrionTracingHooksDir: expect.stringMatching(/@apm-js-collab[/+]tracing-hooks/),
     });
   });
 
@@ -68,6 +105,5 @@ describe('setUpBuildTimeVariables (diagnostics-channel injection)', () => {
     setUpBuildTimeVariables(nextConfig, {}, undefined);
 
     expect(nextConfig.env).not.toHaveProperty('_sentryUseDiagnosticsChannelInjection');
-    expect(nextConfig.env).not.toHaveProperty('_sentryOrchestrionTracingHooksDir');
   });
 });