feat(nuxt)!: Bundle server config into Nitro build (#24094)

Previously, the `sentry.server.config.ts` file was emitted in the build
output so it can be added with `--import`. As we don't rely on
early-importing anymore (thanks to orchestrion), we don't need this file
anymore.


- **Nitro plugin init (default):** The server config is now bundled into
the Nitro build and imported by a generated nitro plugin, so
`Sentry.init` runs at startup without `node --import`. Works on Nitro 2
and 3, prod and dev (hurray)
- **`--import` compat:** The old file path now gets a shim that just
prints "remove this flag". A CI variant runs the whole suite with the
shim preloaded to see if the warning is printed
- **Double init guard:** A preload that really calls `init` wins. The
bundled init skips with a notice.
- **Prerender:** Init is skipped during prerendering, so CI builds send
nothing. Tests assert no trace meta tags in prerendered HTML.
- **Early-crash tests:** Errors thrown before `listen` are captured and
flushed (first and last plugin slot)
- **Deprecated:** both `autoInjectServerSentry` modes, kept working
until v12

Closes #24149

Author: s1gr1d

MIGRATION.md

@@ -1205,6 +1205,34 @@ Affected SDKs: `@sentry/cloudflare`.
 
 Calls to rate limiter bindings (`env.MY_RATE_LIMITER.limit()`) no longer create a span. The removed span had the op `rpc`, the origin `auto.faas.cloudflare.rate_limit`, and the attribute `rpc.service: cloudflare.rate_limit`. Remove any dashboard, alert, or `ignoreSpans` entry that references it.
 
+### `@sentry/nuxt`: the server config is bundled, `--import` is no longer needed
+
+The SDK now bundles `sentry.server.config.ts` into the Nitro server build, where it initializes itself when the server starts. Instrumentation happens at build time, so preloading the config file is no longer necessary.
+
+Remove the `--import` flag from your production start command:
+
+```bash
+# before
+node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs
+
+# after
+node .output/server/index.mjs
+```
+
+Old start commands keep working: the SDK still emits a file at the old path, but it only prints a reminder that the flag can be removed. If you preload a file that calls `Sentry.init` yourself, that init wins and the bundled one is skipped.
+
+The same applies in development. Remove the `NODE_OPTIONS` preload:
+
+```bash
+# before
+NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev
+
+# after
+nuxt dev
+```
+
+Since no preload is needed anymore, the `autoInjectServerSentry` option (`'top-level-import'` and `'experimental_dynamic-import'`) and `experimental_entrypointWrappedFunctions` are deprecated. Remove them from your `sentry` module options as the default behavior replaces both. They will be deleted in the next major version.
+
 ### `@sentry/ember` is now a v2 addon with manual setup
 
 Affected SDKs: `@sentry/ember`.
@@ -1747,11 +1775,7 @@ public/instrument.server.ts
 sentry.server.config.ts
 ```
 
-After the rename, the SDK also emits `.output/server/sentry.server.config.mjs` for you to preload:
-
-```bash
-node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs
-```
+After the rename, the SDK bundles the file into the Nitro server build and initializes itself at server startup. See ["the server config is bundled"](#sentrynuxt-the-server-config-is-bundled---import-is-no-longer-needed) above: the `--import` preload is no longer needed.
 
 The deprecated `sourceMapsUploadOptions` module option was removed. Move its fields to the root level of the `sentry` module options. Note that `url` was renamed to `sentryUrl`, and `enabled` was replaced by `sourcemaps.disable` (inverted: `enabled: false` becomes `sourcemaps: { disable: true }`).
 

dev-packages/e2e-tests/test-applications/nuxt-4-static/nuxt-start-dev-server.bash

@@ -12,7 +12,7 @@
     "clean": "npx nuxi cleanup",
     "test": "playwright test",
     "test:prod": "TEST_ENV=production playwright test",
-    "test:dev": "bash ./nuxt-start-dev-server.bash && TEST_ENV=development playwright test environment",
+    "test:dev": "TEST_ENV=development playwright test environment db-drivers",
     "test:build": "pnpm install && pnpm build",
     "test:build-canary": "pnpm add nuxt@npm:nuxt-nightly@latest && pnpm add nitropack@npm:nitropack-nightly@latest && pnpm install --force && pnpm build",
     "test:assert": "pnpm test:prod && pnpm test:dev"

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

@@ -8,11 +8,12 @@ if (!testEnv) {
 
 const getStartCommand = () => {
   if (testEnv === 'development') {
-    return "NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev -p 3030";
+    // The Sentry server config is bundled into the dev server via a nitro plugin, so no preload is needed.
+    return 'nuxt dev -p 3030';
   }
 
   if (testEnv === 'production') {
-    return 'pnpm start:import';
+    return 'pnpm start';
   }
 
   throw new Error(`Unknown test env: ${testEnv}`);

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

@@ -2,10 +2,14 @@ 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`).
+// `diagnostics_channel` publishers into these drivers as Nitro bundles them. `nuxt dev`
+// has no bundle to transform, so there the drivers rely on runtime injection instead.
 test('Instruments ioredis automatically', async ({ baseURL }) => {
+  // ioredis 5.10.x has no native channels, so dev needs runtime injection — but the dev bundle hoists
+  // its import above the inlined `Sentry.init`, so it loads before injection is active. (ioredis >=5.11
+  // publishes native channels and does work in dev; mysql requires its file lazily, after init.)
+  test.skip(process.env.TEST_ENV === 'development', 'ioredis <5.11 loads before runtime injection is active in dev');
+
   const transactionEventPromise = waitForTransaction('nuxt-4-static', transactionEvent => {
     return (
       transactionEvent.contexts?.trace?.op === 'http.server' && transactionEvent.transaction === 'GET /api/db-ioredis'

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

@@ -0,0 +1,9 @@
+// Simulates a v10-style `node --import` preload that fully initializes the SDK
+// before the config bundled into the server build runs its own `Sentry.init`.
+import * as Sentry from '@sentry/nuxt';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  tracesSampleRate: 1.0,
+  tunnel: 'http://localhost:3031/',
+});

dev-packages/e2e-tests/test-applications/nuxt-4/instrument-preload.mjs

@@ -12,11 +12,13 @@
     "clean": "npx nuxi cleanup",
     "test": "playwright test",
     "test:prod": "TEST_ENV=production playwright test",
-    "test:dev": "bash ./nuxt-start-dev-server.bash && TEST_ENV=development playwright test environment",
-    "test:build": "pnpm install && pnpm build",
-    "test:build-canary": "pnpm add nuxt@npm:nuxt-nightly@latest && pnpm add nitropack@npm:nitropack-nightly@latest && pnpm install --force && pnpm build",
-    "test:assert": "pnpm test:prod && pnpm test:dev"
+    "test:dev": "TEST_ENV=development playwright test environment db-drivers",
+    "test:build": "pnpm install && node ./scripts/build-with-prerender-event-sink.mjs",
+    "test:build-canary": "pnpm add nuxt@npm:nuxt-nightly@latest && pnpm add nitropack@npm:nitropack-nightly@latest && pnpm install --force && node ./scripts/build-with-prerender-event-sink.mjs",
+    "test:assert": "pnpm test:prod && pnpm test:dev",
+    "test:prod:import": "TEST_ENV=production-import playwright test"
   },
+  "//": "Pin ioredis to 5.10.1 because that's the last version before it publishes its own diagnostics channels",
   "dependencies": {
     "@pinia/nuxt": "^0.5.5",
     "@sentry/nuxt": "file:../../packed/sentry-nuxt-packed.tgz",
@@ -38,6 +40,11 @@
         "build-command": "E2E_TEST_OTEL_SETUP=true pnpm test:build",
         "assert-command": "E2E_TEST_OTEL_SETUP=true pnpm test:assert",
         "label": "nuxt-4 (tracer provider)"
+      },
+      {
+        "build-command": "pnpm test:build",
+        "assert-command": "pnpm test:prod:import",
+        "label": "nuxt-4 (--import compat)"
       }
     ],
     "optionalVariants": [

dev-packages/e2e-tests/test-applications/nuxt-4/nuxt-start-dev-server.bash

@@ -8,10 +8,16 @@ if (!testEnv) {
 
 const getStartCommand = () => {
   if (testEnv === 'development') {
-    return "NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev -p 3030";
+    // The Sentry server config is bundled into the dev server via a nitro plugin, so no preload is needed.
+    return 'nuxt dev -p 3030';
   }
 
   if (testEnv === 'production') {
+    return 'pnpm start';
+  }
+
+  // Runs the suite with the compat shim preloaded, like existing `--import` deploy commands do.
+  if (testEnv === 'production-import') {
     return 'pnpm start:import';
   }
 

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

@@ -0,0 +1,30 @@
+// Runs `nuxt build` with a sink on the Sentry tunnel port and records how many envelopes arrive,
+// so tests can assert that prerendering sends no telemetry during the build.
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+
+let envelopeCount = 0;
+const sink = createServer((req, res) => {
+  req.resume();
+  req.on('end', () => {
+    envelopeCount += 1;
+    res.writeHead(200).end('{}');
+  });
+});
+
+const sinkAvailable = await new Promise(resolve => {
+  sink.once('error', () => resolve(false));
+  sink.listen(3031, () => resolve(true));
+});
+
+const build = spawn('nuxt', ['build'], { stdio: 'inherit', shell: true });
+const exitCode = await new Promise(resolve => build.on('exit', resolve));
+
+sink.close();
+mkdirSync('.output', { recursive: true });
+writeFileSync(
+  '.output/build-envelope-count.json',
+  JSON.stringify({ envelopeCount: sinkAvailable ? envelopeCount : null }),
+);
+process.exit(exitCode ?? 1);