feat: sourcemaps upload and debug ID injection

Author: logaretm

packages/nitro/package.json

@@ -38,13 +38,14 @@
     "nitro": ">=3.0.260415-beta"
   },
   "dependencies": {
+    "@sentry/bundler-plugin-core": "^5.2.0",
     "@sentry/core": "10.48.0",
     "@sentry/node": "10.48.0",
     "otel-tracing-channel": "^0.2.0"
   },
   "devDependencies": {
-    "nitro": "^3.0.260415-beta",
-    "h3": "^2.0.1-rc.13"
+    "h3": "^2.0.1-rc.13",
+    "nitro": "^3.0.260415-beta"
   },
   "scripts": {
     "build": "run-p build:transpile build:types",

packages/nitro/rollup.npm.config.mjs

@@ -5,7 +5,7 @@ export default [
     makeBaseNPMConfig({
       entrypoints: ['src/index.ts', 'src/runtime/plugins/server.ts'],
       packageSpecificConfig: {
-        external: [/^nitro/, 'otel-tracing-channel', /^h3/, /^srvx/],
+        external: [/^nitro/, 'otel-tracing-channel', /^h3/, /^srvx/, '@sentry/bundler-plugin-core'],
       },
     }),
   ),

packages/nitro/src/config.ts

@@ -1,34 +1,72 @@
+import type { Options as SentryBundlerPluginOptions } from '@sentry/bundler-plugin-core';
+import { debug } from '@sentry/core';
 import type { NitroConfig } from 'nitro/types';
 import { createNitroModule } from './module';
 
-type SentryNitroOptions = {
-  // TODO: Add options
-};
+export type SentryNitroOptions = Pick<
+  SentryBundlerPluginOptions,
+  | 'org'
+  | 'project'
+  | 'authToken'
+  | 'url'
+  | 'headers'
+  | 'debug'
+  | 'silent'
+  | 'errorHandler'
+  | 'telemetry'
+  | 'disable'
+  | 'sourcemaps'
+  | 'release'
+  | 'bundleSizeOptimizations'
+  | '_metaOptions'
+>;
 
 /**
  * Modifies the passed in Nitro configuration with automatic build-time instrumentation.
- *
- * @param config A Nitro configuration object, as usually exported in `nitro.config.ts` or `nitro.config.mjs`.
- * @returns The modified config to be exported
  */
-export function withSentryConfig(config: NitroConfig, moduleOptions?: SentryNitroOptions): NitroConfig {
-  return setupSentryNitroModule(config, moduleOptions);
+export function withSentryConfig(config: NitroConfig, sentryOptions?: SentryNitroOptions): NitroConfig {
+  return setupSentryNitroModule(config, sentryOptions);
 }
 
 /**
  * Sets up the Sentry Nitro module, useful for meta framework integrations.
  */
 export function setupSentryNitroModule(
   config: NitroConfig,
-  _moduleOptions?: SentryNitroOptions,
+  moduleOptions?: SentryNitroOptions,
   _serverConfigFile?: string,
 ): NitroConfig {
   if (!config.tracingChannel) {
     config.tracingChannel = true;
   }
 
+  const sourcemapUploadDisabled = moduleOptions?.sourcemaps?.disable === true || moduleOptions?.disable === true;
+
+  if (!sourcemapUploadDisabled) {
+    configureSourcemapSettings(config, moduleOptions);
+  }
+
   config.modules = config.modules || [];
-  config.modules.push(createNitroModule());
+  config.modules.push(createNitroModule(moduleOptions));
 
   return config;
 }
+
+function configureSourcemapSettings(config: NitroConfig, moduleOptions?: SentryNitroOptions): void {
+  if (config.sourcemap === false) {
+    debug.warn(
+      '[Sentry] You have explicitly disabled source maps (`sourcemap: false`). Sentry is overriding this to `true` so that errors can be un-minified in Sentry. To disable Sentry source map uploads entirely, use `sourcemaps: { disable: true }` in your Sentry options instead.',
+    );
+  }
+  config.sourcemap = true;
+
+  // Nitro v3 has a `sourcemapMinify` plugin that destructively deletes `sourcesContent`,
+  // `x_google_ignoreList`, and clears `mappings` for any chunk containing `node_modules`.
+  // This makes sourcemaps unusable for Sentry.
+  config.experimental = config.experimental || {};
+  config.experimental.sourcemapMinify = false;
+
+  if (moduleOptions?.debug) {
+    debug.log('[Sentry] Enabled source map generation and configured build settings for Sentry source map uploads.');
+  }
+}

packages/nitro/src/module.ts

@@ -1,14 +1,17 @@
 import type { NitroModule } from 'nitro/types';
+import type { SentryNitroOptions } from './config';
 import { instrumentServer } from './instruments/instrumentServer';
+import { setupSourceMaps } from './sourceMaps';
 
 /**
  * Creates a Nitro module to setup the Sentry SDK.
  */
-export function createNitroModule(): NitroModule {
+export function createNitroModule(sentryOptions?: SentryNitroOptions): NitroModule {
   return {
     name: 'sentry',
     setup: nitro => {
       instrumentServer(nitro);
+      setupSourceMaps(nitro, sentryOptions);
     },
   };
 }

packages/nitro/src/sourceMaps.ts

@@ -0,0 +1,91 @@
+import type { Options } from '@sentry/bundler-plugin-core';
+import { createSentryBuildPluginManager } from '@sentry/bundler-plugin-core';
+import type { Nitro } from 'nitro/types';
+import type { SentryNitroOptions } from './config';
+
+/**
+ * Registers a `compiled` hook to upload source maps after the build completes.
+ */
+export function setupSourceMaps(nitro: Nitro, options?: SentryNitroOptions): void {
+  // The `compiled` hook fires on EVERY rebuild during `nitro dev` watch mode.
+  // nitro.options.dev is reliably set by the time module setup runs.
+  if (nitro.options.dev) {
+    return;
+  }
+
+  // Respect user's explicit disable
+  if (options?.sourcemaps?.disable === true || options?.disable === true) {
+    return;
+  }
+
+  nitro.hooks.hook('compiled', async (_nitro: Nitro) => {
+    await handleSourceMapUpload(_nitro, options);
+  });
+}
+
+/**
+ * Handles the actual source map upload after the build completes.
+ */
+async function handleSourceMapUpload(nitro: Nitro, options?: SentryNitroOptions): Promise<void> {
+  const outputDir = nitro.options.output.serverDir;
+  const pluginOptions = getPluginOptions(options);
+
+  const sentryBuildPluginManager = createSentryBuildPluginManager(pluginOptions, {
+    buildTool: 'nitro',
+    loggerPrefix: '[@sentry/nitro]',
+  });
+
+  await sentryBuildPluginManager.telemetry.emitBundlerPluginExecutionSignal();
+  await sentryBuildPluginManager.createRelease();
+
+  if (options?.sourcemaps?.disable !== 'disable-upload') {
+    await sentryBuildPluginManager.injectDebugIds([outputDir]);
+    await sentryBuildPluginManager.uploadSourcemaps([outputDir], {
+      // We don't prepare the artifacts because we injected debug IDs manually before
+      prepareArtifacts: false,
+    });
+  }
+
+  await sentryBuildPluginManager.deleteArtifacts();
+}
+
+/**
+ * Normalizes the beginning of a path from e.g. ../../../ to ./
+ */
+function normalizePath(path: string): string {
+  return path.replace(/^(\.\.\/)+/, './');
+}
+
+/**
+ * Builds the plugin options for `createSentryBuildPluginManager` from the Sentry Nitro options.
+ *
+ * Only exported for testing purposes.
+ */
+export function getPluginOptions(options?: SentryNitroOptions): Options {
+  return {
+    org: options?.org ?? process.env.SENTRY_ORG,
+    project: options?.project ?? process.env.SENTRY_PROJECT,
+    authToken: options?.authToken ?? process.env.SENTRY_AUTH_TOKEN,
+    url: options?.url ?? process.env.SENTRY_URL,
+    headers: options?.headers,
+    telemetry: options?.telemetry ?? true,
+    debug: options?.debug ?? false,
+    silent: options?.silent ?? false,
+    errorHandler: options?.errorHandler,
+    sourcemaps: {
+      disable: options?.sourcemaps?.disable,
+      assets: options?.sourcemaps?.assets,
+      ignore: options?.sourcemaps?.ignore,
+      filesToDeleteAfterUpload: options?.sourcemaps?.filesToDeleteAfterUpload ?? ['**/*.map'],
+      rewriteSources: (source: string) => normalizePath(source),
+    },
+    release: options?.release,
+    bundleSizeOptimizations: options?.bundleSizeOptimizations,
+    _metaOptions: {
+      telemetry: {
+        metaFramework: 'nitro',
+      },
+      ...options?._metaOptions,
+    },
+  };
+}