feat(nuxt)!: Auto-wire orchestrion build-time instrumentation

dev-packages/e2e-tests/test-applications/nuxt-4-orchestrion/docker-compose.yml → dev-packages/e2e-tests/test-applications/nuxt-4/docker-compose.yml

@@ -2,7 +2,7 @@ services:
   db:
     image: mysql:8.0
     restart: always
-    container_name: e2e-tests-nuxt-4-orchestrion-mysql
+    container_name: e2e-tests-nuxt-4-mysql
     # The `mysql` 2.x driver doesn't speak MySQL 8's default
     # `caching_sha2_password` auth, so force the legacy plugin.
     command: ['--default-authentication-plugin=mysql_native_password']
@@ -20,7 +20,7 @@ services:
   redis:
     image: redis:7
     restart: always
-    container_name: e2e-tests-nuxt-4-orchestrion-redis
+    container_name: e2e-tests-nuxt-4-redis
     ports:
       - '6379:6379'
     healthcheck:

dev-packages/e2e-tests/test-applications/nuxt-4-orchestrion/global-setup.mjs → dev-packages/e2e-tests/test-applications/nuxt-4/global-setup.mjs

@@ -5,8 +5,8 @@ import { fileURLToPath } from 'url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 export default async function globalSetup() {
-  // Start MySQL via Docker Compose. `--wait` blocks until the healthcheck
-  // in docker-compose.yml passes, so the app can connect immediately.
+  // Start MySQL + Redis via Docker Compose. `--wait` blocks until the
+  // healthchecks in docker-compose.yml pass, so the app can connect immediately.
   execSync('docker compose up -d --wait', {
     cwd: __dirname,
     stdio: 'inherit',

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

@@ -20,6 +20,8 @@
   "dependencies": {
     "@pinia/nuxt": "^0.5.5",
     "@sentry/nuxt": "file:../../packed/sentry-nuxt-packed.tgz",
+    "ioredis": "5.10.1",
+    "mysql": "^2.18.1",
     "nuxt": "^4.1.2"
   },
   "devDependencies": {

dev-packages/e2e-tests/test-applications/nuxt-4/playwright.config.ts

@@ -22,4 +22,8 @@ const config = getPlaywrightConfig({
   startCommand: getStartCommand(),
 });
 
-export default config;
+export default {
+  ...config,
+  globalSetup: './global-setup.mjs',
+  globalTeardown: './global-teardown.mjs',
+};

dev-packages/e2e-tests/test-applications/nuxt-4-orchestrion/tests/db.test.ts → dev-packages/e2e-tests/test-applications/nuxt-4/tests/db-drivers.test.ts

@@ -1,8 +1,12 @@
 import { expect, test } from '@playwright/test';
 import { waitForTransaction } from '@sentry-internal/test-utils';
 
+// The Nuxt module auto-wires the orchestrion build-time transform, which injects
+// `diagnostics_channel` publishers into these drivers as Nitro bundles them. That
+// only happens in the production build, so these tests are excluded from the
+// `test:dev` pass (which filters to `environment`).
 test('Instruments ioredis automatically', async ({ baseURL }) => {
-  const transactionEventPromise = waitForTransaction('nuxt-4-orchestrion', transactionEvent => {
+  const transactionEventPromise = waitForTransaction('nuxt-4', transactionEvent => {
     return (
       transactionEvent.contexts?.trace?.op === 'http.server' && transactionEvent.transaction === 'GET /api/db-ioredis'
     );
@@ -46,7 +50,7 @@ test('Instruments ioredis automatically', async ({ baseURL }) => {
 });
 
 test('Instruments mysql automatically', async ({ baseURL }) => {
-  const transactionEventPromise = waitForTransaction('nuxt-4-orchestrion', transactionEvent => {
+  const transactionEventPromise = waitForTransaction('nuxt-4', transactionEvent => {
     return (
       transactionEvent.contexts?.trace?.op === 'http.server' && transactionEvent.transaction === 'GET /api/db-mysql'
     );

packages/nuxt/src/common/types.ts

@@ -183,23 +183,6 @@ export type SentryNuxtModuleOptions = BuildTimeOptionsBase & {
    */
   enabled?: boolean;
 
-  // todo(v11): Update this JSDoc (and remove from experimental)
-  /**
-   * Experimental build-time options that may change or be removed without notice.
-   */
-  _experimental?: {
-    /**
-     * Enables build-time diagnostics-channel instrumentation for supported dependencies bundled into the Nitro server.
-     *
-     * 1. Remove `--import ./.output/server/sentry.server.config.mjs` from your `start` script
-     * 2. Add `sentry.autoInjectServerSentry: 'top-level-import'` in `nuxt.config.ts` so Sentry's server configuration is automatically imported
-     *
-     * @default false
-     * @experimental May change or be removed in any release.
-     */
-    useDiagnosticsChannelInjection?: boolean;
-  };
-
   /**
    * Options for the Sentry Vite plugin to customize the source maps upload process.
    *

packages/nuxt/src/module.ts

@@ -85,9 +85,7 @@ export default defineNuxtModule<ModuleOptions>({
     const isMinNuxtV4 = nuxtMajor >= 4;
 
     if (serverConfigFile) {
-      if (moduleOptions._experimental?.useDiagnosticsChannelInjection) {
-        setupOrchestrion(nuxt);
-      }
+      setupOrchestrion(nuxt, moduleOptions.buildTimeInstrumentation);
 
       if (isNitroV3) {
         addServerPlugin(moduleDirResolver.resolve('./runtime/plugins/handler.server'));

packages/nuxt/src/vite/orchestrion.ts

@@ -11,7 +11,11 @@ const IORedisDependencies = ['standard-as-callback'];
  * Configures Nitro to bundle and transform dependencies that publish tracing
  * events through diagnostics channels.
  */
-export function setupOrchestrion(nuxt: Nuxt): void {
+export function setupOrchestrion(nuxt: Nuxt, buildTimeInstrumentation?: boolean): void {
+  if (buildTimeInstrumentation === false) {
+    return;
+  }
+
   nuxt.hook('nitro:config', (nitroConfig: NitroConfig) => {
     if (nuxt.options?._prepare) {
       return;

packages/nuxt/test/vite/buildOptions.test-d.ts

@@ -51,12 +51,10 @@ describe('Sentry Nuxt build-time options type', () => {
         excludeReplayIframe: true,
         excludeReplayWorker: true,
       },
+      buildTimeInstrumentation: false,
 
       // --- SentryNuxtModuleOptions specific options ---
       enabled: true,
-      _experimental: {
-        useDiagnosticsChannelInjection: true,
-      },
       autoInjectServerSentry: 'experimental_dynamic-import',
       configDir: '~/custom-config',
       experimental_entrypointWrappedFunctions: ['default', 'handler', 'server', 'customExport'],

packages/nuxt/test/vite/orchestrion.test.ts

@@ -70,6 +70,18 @@ describe('setupOrchestrion', () => {
     });
   });
 
+  it('does not change Nitro configuration when `buildTimeInstrumentation` is `false`', async () => {
+    const { setupOrchestrion } = await import('../../src/vite/orchestrion');
+    const mockNuxt = createMockNuxt();
+    const nitroConfig = {};
+
+    setupOrchestrion(mockNuxt as unknown as Nuxt, false);
+    await mockNuxt.triggerHook('nitro:config', nitroConfig);
+
+    expect(mockSentryOrchestrionPlugin).not.toHaveBeenCalled();
+    expect(nitroConfig).toEqual({});
+  });
+
   it('does not change Nitro configuration in prepare mode', async () => {
     const { setupOrchestrion } = await import('../../src/vite/orchestrion');
     const mockNuxt = createMockNuxt({ _prepare: true });