feat(tanstackstart-react): Add sentryTanstackStart vite plugin to manage automatic source map uploads

dev-packages/e2e-tests/test-applications/tanstackstart-react/vite.config.ts

@@ -3,16 +3,27 @@ import tsConfigPaths from 'vite-tsconfig-paths';
 import { tanstackStart } from '@tanstack/react-start/plugin/vite';
 import viteReact from '@vitejs/plugin-react-swc';
 import { nitro } from 'nitro/vite';
+import { wrapConfigWithSentry } from '@sentry/tanstackstart-react';
 
-export default defineConfig({
-  server: {
-    port: 3000,
-  },
-  plugins: [
-    tsConfigPaths(),
-    tanstackStart(),
-    nitro(),
-    // react's vite plugin must come after start's vite plugin
-    viteReact(),
-  ],
-});
+export default defineConfig(
+  wrapConfigWithSentry(
+    {
+      server: {
+        port: 3000,
+      },
+      plugins: [
+        tsConfigPaths(),
+        tanstackStart(),
+        nitro(),
+        // react's vite plugin must come after start's vite plugin
+        viteReact(),
+      ],
+    },
+    {
+      org: process.env.E2E_TEST_SENTRY_ORG_SLUG,
+      project: process.env.E2E_TEST_SENTRY_PROJECT,
+      authToken: process.env.E2E_TEST_AUTH_TOKEN,
+      debug: true,
+    },
+  ),
+);

packages/solidstart/src/vite/sourceMaps.ts

@@ -76,7 +76,7 @@ export function makeEnableSourceMapsVitePlugin(options: SentrySolidStartPluginOp
   ];
 }
 
-/** There are 3 ways to set up source map generation (https://github.com/getsentry/sentry-j avascript/issues/13993)
+/** There are 3 ways to set up source map generation (https://github.com/getsentry/sentry-javascript/issues/13993)
  *
  *     1. User explicitly disabled source maps
  *       - keep this setting (emit a warning that errors won't be unminified in Sentry)

packages/tanstackstart-react/package.json

@@ -55,7 +55,11 @@
     "@sentry-internal/browser-utils": "10.32.1",
     "@sentry/core": "10.32.1",
     "@sentry/node": "10.32.1",
-    "@sentry/react": "10.32.1"
+    "@sentry/react": "10.32.1",
+    "@sentry/vite-plugin": "^4.6.1"
+  },
+  "devDependencies": {
+    "vite": "^5.4.11"
   },
   "scripts": {
     "build": "run-p build:transpile build:types",

packages/tanstackstart-react/src/config/index.ts

@@ -1 +1,2 @@
-export {};
+export * from './types';
+export { wrapConfigWithSentry } from './wrapConfigWithSentry';

packages/tanstackstart-react/src/config/types.ts

@@ -0,0 +1,111 @@
+type BundleSizeOptimizationOptions = {
+  /**
+   * If set to `true`, the plugin will attempt to tree-shake (remove) any debugging code within the Sentry SDK.
+   * Note that the success of this depends on tree shaking being enabled in your build tooling.
+   *
+   * Setting this option to `true` will disable features like the SDK's `debug` option.
+   */
+  excludeDebugStatements?: boolean;
+
+  /**
+   * If set to true, the plugin will try to tree-shake tracing statements out.
+   * Note that the success of this depends on tree shaking generally being enabled in your build.
+   * Attention: DO NOT enable this when you're using any performance monitoring-related SDK features (e.g. Sentry.startSpan()).
+   */
+  excludeTracing?: boolean;
+
+  /**
+   * If set to `true`, the plugin will attempt to tree-shake (remove) code related to the Sentry SDK's Session Replay Shadow DOM recording functionality.
+   * Note that the success of this depends on tree shaking being enabled in your build tooling.
+   *
+   * This option is safe to be used when you do not want to capture any Shadow DOM activity via Sentry Session Replay.
+   */
+  excludeReplayShadowDom?: boolean;
+
+  /**
+   * If set to `true`, the plugin will attempt to tree-shake (remove) code related to the Sentry SDK's Session Replay `iframe` recording functionality.
+   * Note that the success of this depends on tree shaking being enabled in your build tooling.
+   *
+   * You can safely do this when you do not want to capture any `iframe` activity via Sentry Session Replay.
+   */
+  excludeReplayIframe?: boolean;
+
+  /**
+   * If set to `true`, the plugin will attempt to tree-shake (remove) code related to the Sentry SDK's Session Replay's Compression Web Worker.
+   * Note that the success of this depends on tree shaking being enabled in your build tooling.
+   *
+   * **Notice:** You should only do use this option if you manually host a compression worker and configure it in your Sentry Session Replay integration config via the `workerUrl` option.
+   */
+  excludeReplayWorker?: boolean;
+};
+
+type SourceMapsOptions = {
+  /**
+   * If this flag is `true`, and an auth token is detected, the Sentry SDK will
+   * automatically generate and upload source maps to Sentry during a production build.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * If this flag is `true`, the Sentry plugin will collect some telemetry data and send it to Sentry.
+   * It will not collect any sensitive or user-specific data.
+   *
+   * @default true
+   */
+  telemetry?: boolean;
+
+  /**
+   * A glob or an array of globs that specifies the build artifacts that should be deleted after the artifact
+   * upload to Sentry has been completed.
+   *
+   * @default [] - By default no files are deleted.
+   *
+   * The globbing patterns follow the implementation of the glob package. (https://www.npmjs.com/package/glob)
+   */
+  filesToDeleteAfterUpload?: string | Array<string>;
+};
+
+/**
+ * Build options for the Sentry plugin. These options are used during build-time by the Sentry SDK.
+ */
+export type SentryTanstackStartReactPluginOptions = {
+  /**
+   * The auth token to use when uploading source maps to Sentry.
+   *
+   * Instead of specifying this option, you can also set the `SENTRY_AUTH_TOKEN` environment variable.
+   *
+   * To create an auth token, follow this guide:
+   * @see https://docs.sentry.io/product/accounts/auth-tokens/#organization-auth-tokens
+   */
+  authToken?: string;
+
+  /**
+   * The organization slug of your Sentry organization.
+   * Instead of specifying this option, you can also set the `SENTRY_ORG` environment variable.
+   */
+  org?: string;
+
+  /**
+   * The project slug of your Sentry project.
+   * Instead of specifying this option, you can also set the `SENTRY_PROJECT` environment variable.
+   */
+  project?: string;
+
+  /**
+   * Options for the Sentry Vite plugin to customize the source maps upload process.
+   */
+  sourceMapsUploadOptions?: SourceMapsOptions;
+
+  /**
+   * Options for the Sentry Vite plugin to customize bundle size optimizations.
+   */
+  bundleSizeOptimizations?: BundleSizeOptimizationOptions;
+
+  /**
+   * Enable debug functionality of the SDK during build-time.
+   * Enabling this will give you, for example logs about source maps.
+   */
+  debug?: boolean;
+};

packages/tanstackstart-react/src/config/wrapConfigWithSentry.ts

@@ -0,0 +1,45 @@
+import type { UserConfig } from 'vite';
+import { addSentryPlugins } from '../vite';
+import type { SentryTanstackStartReactPluginOptions } from './types';
+
+/**
+ * Wraps a Vite configuration object with Sentry build-time enhancements such as
+ * automatic source maps upload.
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import { wrapConfigWithSentry } from '@sentry/tanstackstart-react';
+ *
+ * export default defineConfig(
+ *   wrapConfigWithSentry(
+ *     {
+ *       // Your Vite/TanStack Start config
+ *       plugins: [...]
+ *     },
+ *     {
+ *       // Sentry build-time options
+ *       org: 'your-org',
+ *       project: 'your-project',
+ *     },
+ *   ),
+ * );
+ * ```
+ *
+ * @param config - A Vite configuration object
+ * @param sentryPluginOptions - Options to configure the Sentry Vite plugin
+ * @returns The modified Vite config to be passed to `defineConfig`
+ */
+export function wrapConfigWithSentry(
+  config: UserConfig = {},
+  sentryPluginOptions: SentryTanstackStartReactPluginOptions = {},
+): UserConfig {
+  const userPlugins = Array.isArray(config.plugins) ? [...config.plugins] : [];
+  const plugins = addSentryPlugins(userPlugins, sentryPluginOptions, config);
+
+  return {
+    ...config,
+    plugins,
+  };
+}

packages/tanstackstart-react/src/vite/addSentryPlugins.ts

@@ -0,0 +1,31 @@
+import type { PluginOption, UserConfig } from 'vite';
+import type { SentryTanstackStartReactPluginOptions } from '../config/types';
+import { makeAddSentryVitePlugin, makeEnableSourceMapsVitePlugin } from './sourceMaps';
+
+/**
+ * Adds Sentry plugins to the given array of Vite plugins.
+ */
+export function addSentryPlugins(
+  plugins: PluginOption[],
+  options: SentryTanstackStartReactPluginOptions,
+  viteConfig: UserConfig,
+): PluginOption[] {
+  const sentryPlugins: PluginOption[] = [];
+
+  // Only add source map plugins in production builds
+  if (process.env.NODE_ENV !== 'development') {
+    // Check if source maps upload is enabled
+    // Default to enabled
+    const sourceMapsEnabled = options.sourceMapsUploadOptions?.enabled ?? true;
+
+    if (sourceMapsEnabled) {
+      const sourceMapsPlugins = makeAddSentryVitePlugin(options, viteConfig);
+      const enableSourceMapsPlugin = makeEnableSourceMapsVitePlugin(options);
+
+      sentryPlugins.push(...sourceMapsPlugins, ...enableSourceMapsPlugin);
+    }
+  }
+
+  // Prepend Sentry plugins so they run first
+  return [...sentryPlugins, ...plugins];
+}

packages/tanstackstart-react/src/vite/index.ts

@@ -0,0 +1 @@
+export { addSentryPlugins } from './addSentryPlugins';

packages/tanstackstart-react/src/vite/sourceMaps.ts

@@ -0,0 +1,136 @@
+import { sentryVitePlugin } from '@sentry/vite-plugin';
+import type { Plugin, UserConfig } from 'vite';
+import type { SentryTanstackStartReactPluginOptions } from '../config/types';
+
+/**
+ * A Sentry plugin for adding the @sentry/vite-plugin to automatically upload source maps to Sentry.
+ */
+export function makeAddSentryVitePlugin(
+  options: SentryTanstackStartReactPluginOptions,
+  viteConfig: UserConfig,
+): Plugin[] {
+  const { authToken, bundleSizeOptimizations, debug, org, project, sourceMapsUploadOptions } = options;
+
+  let updatedFilesToDeleteAfterUpload: string[] | undefined = undefined;
+
+  if (
+    typeof sourceMapsUploadOptions?.filesToDeleteAfterUpload === 'undefined' &&
+    // Only if source maps were previously not set, we update the "filesToDeleteAfterUpload" (as we override the setting with "hidden")
+    typeof viteConfig.build?.sourcemap === 'undefined'
+  ) {
+    // For .output, .vercel, .netlify etc.
+    updatedFilesToDeleteAfterUpload = ['.*/**/*.map'];
+
+    if (debug) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[Sentry] Automatically setting \`sourceMapsUploadOptions.filesToDeleteAfterUpload: ${JSON.stringify(
+          updatedFilesToDeleteAfterUpload,
+        )}\` to delete generated source maps after they were uploaded to Sentry.`,
+      );
+    }
+  }
+
+  return [
+    ...sentryVitePlugin({
+      authToken: authToken ?? process.env.SENTRY_AUTH_TOKEN,
+      bundleSizeOptimizations: bundleSizeOptimizations ?? undefined,
+      debug: debug ?? false,
+      org: org ?? process.env.SENTRY_ORG,
+      project: project ?? process.env.SENTRY_PROJECT,
+      sourcemaps: {
+        filesToDeleteAfterUpload: sourceMapsUploadOptions?.filesToDeleteAfterUpload ?? updatedFilesToDeleteAfterUpload,
+      },
+      telemetry: sourceMapsUploadOptions?.telemetry ?? true,
+      _metaOptions: {
+        telemetry: {
+          metaFramework: 'tanstackstart-react',
+        },
+      },
+    }),
+  ];
+}
+
+/**
+ * A Sentry plugin for TanStack Start React to enable "hidden" source maps if they are unset.
+ */
+export function makeEnableSourceMapsVitePlugin(options: SentryTanstackStartReactPluginOptions): Plugin[] {
+  return [
+    {
+      name: 'sentry-tanstackstart-react-source-maps',
+      apply: 'build',
+      enforce: 'post',
+      config(viteConfig) {
+        return {
+          ...viteConfig,
+          build: {
+            ...viteConfig.build,
+            sourcemap: getUpdatedSourceMapSettings(viteConfig, options),
+          },
+        };
+      },
+    },
+  ];
+}
+
+/** There are 3 ways to set up source map generation (https://github.com/getsentry/sentry-javascript/issues/13993)
+ *
+ *     1. User explicitly disabled source maps
+ *       - keep this setting (emit a warning that errors won't be unminified in Sentry)
+ *       - We won't upload anything
+ *
+ *     2. Users enabled source map generation (true, 'hidden', 'inline').
+ *       - keep this setting (don't do anything - like deletion - besides uploading)
+ *
+ *     3. Users didn't set source maps generation
+ *       - we enable 'hidden' source maps generation
+ *       - configure `filesToDeleteAfterUpload` to delete all .map files (we emit a log about this)
+ *
+ * --> only exported for testing
+ */
+export function getUpdatedSourceMapSettings(
+  viteConfig: UserConfig,
+  sentryPluginOptions?: SentryTanstackStartReactPluginOptions,
+): boolean | 'inline' | 'hidden' {
+  viteConfig.build = viteConfig.build || {};
+
+  const viteSourceMap = viteConfig.build?.sourcemap;
+  let updatedSourceMapSetting = viteSourceMap;
+
+  const settingKey = 'vite.build.sourcemap';
+  const debug = sentryPluginOptions?.debug;
+
+  if (viteSourceMap === false) {
+    updatedSourceMapSetting = viteSourceMap;
+
+    if (debug) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[Sentry] Source map generation is currently disabled in your TanStack Start configuration (\`${settingKey}: false\`). Sentry won't override this setting. Without source maps, code snippets on the Sentry Issues page will remain minified.`,
+      );
+    } else {
+      // eslint-disable-next-line no-console
+      console.warn('[Sentry] Source map generation is disabled in your TanStack Start configuration.');
+    }
+  } else if (viteSourceMap && ['hidden', 'inline', true].includes(viteSourceMap)) {
+    updatedSourceMapSetting = viteSourceMap;
+
+    if (debug) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[Sentry] We discovered \`${settingKey}\` is set to \`${viteSourceMap.toString()}\`. Sentry will keep this source map setting.`,
+      );
+    }
+  } else {
+    updatedSourceMapSetting = 'hidden';
+
+    if (debug) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[Sentry] Enabled source map generation in the build options with \`${settingKey}: 'hidden'\`. The source maps will be deleted after they were uploaded to Sentry.`,
+      );
+    }
+  }
+
+  return updatedSourceMapSetting;
+}