feat(remix): Auto-wire orchestrion build-time instrumentation

MIGRATION.md

@@ -1272,6 +1272,8 @@ Affected SDKs: `@sentry/remix`.
 + import { sentryRemixVitePlugin } from '@sentry/remix/vite';
 ```
 
+The plugin now also applies the build-time instrumentation transform. If you added `sentryOrchestrionPlugin()` from `@sentry/server-utils/orchestrion/vite` to your Vite config manually, remove it. Opt out with `sentryRemixVitePlugin({ buildTimeInstrumentation: false })`.
+
 ## 3. Removed APIs
 
 ### `@sentry/core` / All SDKs

dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json

@@ -13,7 +13,6 @@
   },
   "dependencies": {
     "@sentry/remix": "file:../../packed/sentry-remix-packed.tgz",
-    "@sentry/server-utils": "file:../../packed/sentry-server-utils-packed.tgz",
     "@remix-run/css-bundle": "2.17.4",
     "@remix-run/node": "2.17.4",
     "@remix-run/react": "2.17.4",

dev-packages/e2e-tests/test-applications/create-remix-app-v2/vite.config.ts

@@ -1,6 +1,5 @@
 import { vitePlugin as remix } from '@remix-run/dev';
 import { sentryRemixVitePlugin } from '@sentry/remix/vite';
-import { sentryOrchestrionPlugin } from '@sentry/server-utils/orchestrion/vite';
 import { defineConfig } from 'vite';
 import tsconfigPaths from 'vite-tsconfig-paths';
 
@@ -10,10 +9,6 @@ export default defineConfig({
       ignoredRouteFiles: ['**/.*'],
     }),
     sentryRemixVitePlugin(),
-    // Run the orchestrion code transform over the SSR server bundle and force-bundle the
-    // instrumented deps (mysql, ioredis, @remix-run/server-runtime, …) so their
-    // diagnostics-channel calls are injected at build time.
-    sentryOrchestrionPlugin(),
     tsconfigPaths(),
   ],
 });

packages/remix/src/vite/index.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from 'vite';
+import { makeOrchestrionPlugin } from './orchestrionPlugin';
 import { makeRouteManifestPlugin } from './routeManifestPlugin';
 import type { SentryRemixVitePluginOptions } from './types';
 
@@ -7,8 +8,9 @@ export type { SentryRemixVitePluginOptions };
 /**
  * Sentry Vite plugins for Remix.
  *
- * Add these to your Vite configuration to inject the Remix route manifest, so client-side
- * transactions are parameterized.
+ * Add these to your Vite configuration to
+ * - inject the Remix route manifest, so client-side transactions are parameterized, and
+ * - build-time instrument supported server-side dependencies (such as database clients).
  *
  * @example
  * ```typescript
@@ -28,5 +30,5 @@ export type { SentryRemixVitePluginOptions };
  * ```
  */
 export function sentryRemixVitePlugin(options: SentryRemixVitePluginOptions = {}): Plugin[] {
-  return [makeRouteManifestPlugin(options)];
+  return [makeRouteManifestPlugin(options), makeOrchestrionPlugin(options)];
 }

packages/remix/src/vite/orchestrionPlugin.ts

@@ -0,0 +1,81 @@
+import { sentryOrchestrionPlugin } from '@sentry/server-utils/orchestrion/vite';
+import type { ConfigEnv, Plugin, ResolvedConfig, UserConfig } from 'vite';
+import type { SentryRemixVitePluginOptions } from './types';
+
+type AnyHook = (this: unknown, ...args: never[]) => unknown;
+type ObjectHook<T> = T | { order?: 'pre' | 'post' | null; handler: T };
+type ConfigHook = (this: unknown, config: UserConfig, env: ConfigEnv) => unknown;
+
+const WORKER_RESOLVE_CONDITIONS = ['workerd', 'worker'];
+
+/**
+ * Cloudflare Pages and Hydrogen/Oxygen builds instrument through `instrumentBuild()` from
+ * `@sentry/remix/cloudflare`, which wraps the build instead of subscribing to diagnostics
+ * channels. Transforming there would add a `node:diagnostics_channel` import and subscriber code
+ * that nothing reads.
+ *
+ * Oxygen sets `ssr.target`, but Remix's own Vite plugin never does — a Cloudflare app is marked by
+ * workerd resolve conditions instead (`cloudflareDevProxyVitePlugin` sets `externalConditions`,
+ * the Cloudflare template sets `conditions`), so all three signals have to be checked.
+ */
+function isWorkerTarget(config: UserConfig | ResolvedConfig | undefined): boolean {
+  const ssr = config?.ssr;
+  if (ssr?.target === 'webworker') {
+    return true;
+  }
+
+  return [ssr?.resolve?.conditions, ssr?.resolve?.externalConditions].some(conditions =>
+    conditions?.some(condition => WORKER_RESOLVE_CONDITIONS.includes(condition)),
+  );
+}
+
+function hookHandler<T extends AnyHook>(hook: ObjectHook<T> | undefined): T | undefined {
+  return typeof hook === 'function' ? hook : hook?.handler;
+}
+
+/** No-ops a hook while `isDisabled()` holds, keeping its declared hook shape. */
+function gateHook<T extends AnyHook>(
+  hook: ObjectHook<T> | undefined,
+  isDisabled: () => boolean,
+): ObjectHook<T> | undefined {
+  if (!hook) {
+    return hook;
+  }
+
+  const handler = hookHandler(hook) as AnyHook;
+  const gated = function (this: unknown, ...args: never[]): unknown {
+    return isDisabled() ? null : handler.apply(this, args);
+  } as T;
+
+  return typeof hook === 'function' ? gated : { ...hook, handler: gated };
+}
+
+/** The orchestrion bundler plugin, wired to stay out of workerd builds. */
+export function makeOrchestrionPlugin(options: Pick<SentryRemixVitePluginOptions, 'buildTimeInstrumentation'>): Plugin {
+  const orchestrion = sentryOrchestrionPlugin({ buildTimeInstrumentation: options.buildTimeInstrumentation });
+  const { renderChunk } = orchestrion as Plugin & { renderChunk?: ObjectHook<AnyHook> };
+  const config = hookHandler(orchestrion.config as ObjectHook<ConfigHook> | undefined);
+  const configResolved = hookHandler(orchestrion.configResolved);
+
+  let isWorkerBuild = false;
+
+  return {
+    ...orchestrion,
+    // Upstream ships the plugin with `enforce: 'pre'`, which would run this hook before the
+    // framework plugins that set `ssr.target`. `order: 'post'` moves it after them.
+    config: {
+      order: 'post',
+      handler(userConfig: UserConfig, env: ConfigEnv) {
+        return isWorkerTarget(userConfig) ? null : (config?.(userConfig, env) ?? null);
+      },
+    },
+    // The authoritative check: the resolved config reflects every plugin regardless of ordering,
+    // and this always runs before the first `transform`.
+    configResolved(resolvedConfig: ResolvedConfig) {
+      isWorkerBuild = isWorkerTarget(resolvedConfig);
+      return isWorkerBuild ? undefined : configResolved?.(resolvedConfig);
+    },
+    transform: gateHook(orchestrion.transform as ObjectHook<AnyHook> | undefined, () => isWorkerBuild),
+    renderChunk: gateHook(renderChunk, () => isWorkerBuild),
+  } as Plugin;
+}

packages/remix/src/vite/types.ts

@@ -8,4 +8,15 @@ export type SentryRemixVitePluginOptions = {
    * @example '/absolute/path/to/app'
    */
   appDirPath?: string;
+
+  /**
+   * Build-time instrumentation of server-side dependencies (e.g. `mysql`, `ioredis`,
+   * `@remix-run/server-runtime`): the plugin injects `diagnostics_channel` publishers into the
+   * bundled SSR output, so the SDK traces them without monkey-patching.
+   *
+   * Set to `false` to opt out.
+   *
+   * @default true
+   */
+  buildTimeInstrumentation?: boolean;
 };

packages/remix/test/vite/index.test.ts

@@ -0,0 +1,121 @@
+import type { ConfigEnv, UserConfig } from 'vite';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { sentryRemixVitePlugin } from '../../src/vite';
+
+// Stub the orchestrion plugin so these stay pure wiring tests (no apm code transformer pulled in),
+// mirroring the real plugin's two shapes.
+const orchestrionConfig = vi.fn((_config: UserConfig, env: ConfigEnv) =>
+  env.command === 'serve' ? null : { ssr: { noExternal: ['mysql'] } },
+);
+const orchestrionConfigResolved = vi.fn();
+const orchestrionTransform = vi.fn(() => ({ code: 'transformed' }));
+
+const orchestrionVite = vi.fn((options?: { buildTimeInstrumentation?: boolean }) =>
+  options?.buildTimeInstrumentation === false
+    ? { name: 'sentry-orchestrion-disabled' }
+    : {
+        name: 'code-transformer',
+        enforce: 'pre',
+        config: orchestrionConfig,
+        configResolved: orchestrionConfigResolved,
+        transform: orchestrionTransform,
+      },
+);
+
+vi.mock('@sentry/server-utils/orchestrion/vite', () => ({
+  sentryOrchestrionPlugin: (options?: { buildTimeInstrumentation?: boolean }) => orchestrionVite(options),
+}));
+
+const NODE_CONFIG = { ssr: { target: 'node' } } as UserConfig;
+const WORKER_CONFIG = { ssr: { target: 'webworker' } } as UserConfig;
+// Remix's own Vite plugin never sets `ssr.target`, so a Cloudflare app is only recognizable by its
+// workerd resolve conditions: `cloudflareDevProxyVitePlugin` contributes `externalConditions`, the
+// Cloudflare template sets `conditions` in the user's own config.
+const WORKER_CONFIGS: Array<[string, UserConfig]> = [
+  ['ssr.target', WORKER_CONFIG],
+  ['ssr.resolve.conditions', { ssr: { resolve: { conditions: ['workerd', 'worker', 'browser'] } } } as UserConfig],
+  ['ssr.resolve.externalConditions', { ssr: { resolve: { externalConditions: ['workerd', 'worker'] } } } as UserConfig],
+];
+const BUILD_ENV = { command: 'build', mode: 'production' } as ConfigEnv;
+const SERVE_ENV = { command: 'serve', mode: 'development' } as ConfigEnv;
+
+/** Calls a hook declared in either the bare-function or the `{ handler }` form. */
+function callHook(hook: unknown, ...args: unknown[]): unknown {
+  const handler = typeof hook === 'function' ? hook : (hook as { handler: (...a: unknown[]) => unknown }).handler;
+  return (handler as (...a: unknown[]) => unknown)(...args);
+}
+
+describe('sentryRemixVitePlugin', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns the route manifest plugin and the orchestrion plugin', () => {
+    const plugins = sentryRemixVitePlugin();
+
+    expect(plugins.map(plugin => plugin.name)).toEqual(['sentry-remix-route-manifest', 'code-transformer']);
+    expect(orchestrionVite).toHaveBeenCalledWith({ buildTimeInstrumentation: undefined });
+  });
+
+  it('adds an inert orchestrion plugin when `buildTimeInstrumentation` is `false`', () => {
+    const plugins = sentryRemixVitePlugin({ buildTimeInstrumentation: false });
+
+    expect(orchestrionVite).toHaveBeenCalledWith({ buildTimeInstrumentation: false });
+    expect(plugins.map(plugin => plugin.name)).toContain('sentry-orchestrion-disabled');
+  });
+
+  it('keeps the upstream `enforce: "pre"` but defers its `config` hook to the end', () => {
+    const orchestrion = sentryRemixVitePlugin()[1] as { enforce?: string; config?: { order?: string } };
+
+    expect(orchestrion.enforce).toBe('pre');
+    expect(orchestrion.config?.order).toBe('post');
+  });
+
+  // The dev server keeps instrumented deps external and lets the runtime `--import` hook inject the
+  // channels, which the orchestrion plugin decides from `env.command` — so the wrapper has to pass
+  // it through untouched.
+  it('forwards the config env so the plugin can opt out in the dev server', () => {
+    const orchestrion = sentryRemixVitePlugin()[1]!;
+
+    expect(callHook(orchestrion.config, NODE_CONFIG, SERVE_ENV)).toBeNull();
+    expect(orchestrionConfig).toHaveBeenCalledWith(NODE_CONFIG, SERVE_ENV);
+  });
+
+  describe('worker targets', () => {
+    it('applies the orchestrion hooks for node builds', () => {
+      const orchestrion = sentryRemixVitePlugin()[1]!;
+
+      expect(callHook(orchestrion.config, NODE_CONFIG, BUILD_ENV)).toEqual({ ssr: { noExternal: ['mysql'] } });
+
+      callHook(orchestrion.configResolved, NODE_CONFIG);
+      expect(orchestrionConfigResolved).toHaveBeenCalledTimes(1);
+
+      expect(callHook(orchestrion.transform, 'code', 'mysql.js', { ssr: true })).toEqual({ code: 'transformed' });
+    });
+
+    it.each(WORKER_CONFIGS)('skips force-bundling and transforming when %s marks a worker', (_signal, config) => {
+      const orchestrion = sentryRemixVitePlugin()[1]!;
+
+      expect(callHook(orchestrion.config, config, BUILD_ENV)).toBeNull();
+      expect(orchestrionConfig).not.toHaveBeenCalled();
+
+      callHook(orchestrion.configResolved, config);
+      expect(orchestrionConfigResolved).not.toHaveBeenCalled();
+
+      expect(callHook(orchestrion.transform, 'code', 'mysql.js', { ssr: true })).toBeNull();
+      expect(orchestrionTransform).not.toHaveBeenCalled();
+    });
+
+    // Framework plugins can set `ssr.target` after our `config` hook ran, so `configResolved` is
+    // what actually has to keep the transform out of a worker bundle.
+    it('skips the transform when the worker target only shows up in the resolved config', () => {
+      const orchestrion = sentryRemixVitePlugin()[1]!;
+
+      callHook(orchestrion.config, {} as UserConfig, BUILD_ENV);
+      callHook(orchestrion.configResolved, WORKER_CONFIG);
+
+      expect(callHook(orchestrion.transform, 'code', 'mysql.js', { ssr: true })).toBeNull();
+      expect(orchestrionTransform).not.toHaveBeenCalled();
+    });
+  });
+});