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

Adds sentryTanstackStart Vite plugin to enable automatic source map
uploads in TanStack Start applications.

**What it does**
I tried to align with what we do in other SDKs (e.g. SvelteKit). On a
high-level it:
- Uploads source maps to Sentry using @sentry/vite-plugin if configured,
passing through all options set by the user (including release,
sourcemaps, headers, etc.)
- If the source maps option is not defined and also the files to delete
option is not defined, we enable cleaning up all .map files after the
source map upload
- If the source map configuration is undefined, we additionally enable
hidden source map generation

 **Usage**

```
// vite.config.ts
  import { defineConfig } from 'vite';
  import { sentryTanstackStart } from '@sentry/tanstackstart-react';
  import { tanstackStart } from '@tanstack/react-start/plugin/vite';

  export default defineConfig({
    plugins: [
      sentryTanstackStart({
        authToken: process.env.SENTRY_AUTH_TOKEN,
        org: 'my-org',
        project: 'my-project',
      }),
      tanstackStart(),
    ],
  });
```

**Tests**
- Added unit tests for sourceMaps.ts and sentryTanstackStart.ts covering
plugin composition, options passing, and source map settings logic
- Updated the E2E test to use the new plugin pattern

Closes #18664

Author: nicohrubec

CHANGELOG.md

@@ -4,6 +4,28 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(tanstackstart-react): Add `sentryTanstackStart` Vite plugin for source maps upload**
+
+  You can now configure source maps upload for TanStack Start using the `sentryTanstackStart` Vite plugin:
+
+  ```ts
+  // vite.config.ts
+  import { defineConfig } from 'vite';
+  import { sentryTanstackStart } from '@sentry/tanstackstart-react';
+  import { tanstackStart } from '@tanstack/react-start/plugin/vite';
+
+  export default defineConfig({
+    plugins: [
+      sentryTanstackStart({
+        authToken: process.env.SENTRY_AUTH_TOKEN,
+        org: 'your-org',
+        project: 'your-project',
+      }),
+      tanstackStart(),
+    ],
+  });
+  ```
+
 Work in this release was contributed by @rreckonerr. Thank you for your contribution!
 
 ## 10.34.0

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

@@ -3,12 +3,19 @@ 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 { sentryTanstackStart } from '@sentry/tanstackstart-react';
 
 export default defineConfig({
   server: {
     port: 3000,
   },
   plugins: [
+    sentryTanstackStart({
+      org: process.env.E2E_TEST_SENTRY_ORG_SLUG,
+      project: process.env.E2E_TEST_SENTRY_PROJECT,
+      authToken: process.env.E2E_TEST_AUTH_TOKEN,
+      debug: true,
+    }),
     tsConfigPaths(),
     tanstackStart(),
     nitro(),

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.34.0",
     "@sentry/core": "10.34.0",
     "@sentry/node": "10.34.0",
-    "@sentry/react": "10.34.0"
+    "@sentry/react": "10.34.0",
+    "@sentry/vite-plugin": "^4.6.2"
+  },
+  "devDependencies": {
+    "vite": "^5.4.11"
   },
   "scripts": {
     "build": "run-p build:transpile build:types",

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

@@ -3,3 +3,4 @@
 export * from './config';
 export * from './server';
 export * from './common';
+export * from './vite';

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

@@ -12,6 +12,7 @@ export * from './config';
 export * from './client';
 export * from './server';
 export * from './common';
+export * from './vite';
 
 /** Initializes Sentry TanStack Start SDK */
 export declare function init(options: Options | clientSdk.BrowserOptions | serverSdk.NodeOptions): Client | undefined;

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

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

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

@@ -0,0 +1,43 @@
+import type { BuildTimeOptionsBase } from '@sentry/core';
+import type { Plugin } from 'vite';
+import { makeAddSentryVitePlugin, makeEnableSourceMapsVitePlugin } from './sourceMaps';
+
+/**
+ * Vite plugins for the Sentry TanStack Start SDK.
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import { sentryTanstackStart } from '@sentry/tanstackstart-react';
+ * import { tanstackStart } from '@tanstack/react-start/plugin/vite';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     sentryTanstackStart({
+ *       org: 'your-org',
+ *       project: 'your-project',
+ *     }),
+ *     tanstackStart(),
+ *   ],
+ * });
+ * ```
+ *
+ * @param options - Options to configure the Sentry Vite plugins
+ * @returns An array of Vite plugins
+ */
+export function sentryTanstackStart(options: BuildTimeOptionsBase = {}): Plugin[] {
+  // Only add plugins in production builds
+  if (process.env.NODE_ENV === 'development') {
+    return [];
+  }
+
+  const plugins: Plugin[] = [...makeAddSentryVitePlugin(options)];
+
+  const sourceMapsDisabled = options.sourcemaps?.disable === true || options.sourcemaps?.disable === 'disable-upload';
+  if (!sourceMapsDisabled) {
+    plugins.push(...makeEnableSourceMapsVitePlugin(options));
+  }
+
+  return plugins;
+}

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

@@ -0,0 +1,162 @@
+import type { BuildTimeOptionsBase } from '@sentry/core';
+import { sentryVitePlugin } from '@sentry/vite-plugin';
+import type { Plugin, UserConfig } from 'vite';
+
+type FilesToDeleteAfterUpload = string | string[] | undefined;
+
+/**
+ * A Sentry plugin for adding the @sentry/vite-plugin to automatically upload source maps to Sentry.
+ */
+export function makeAddSentryVitePlugin(options: BuildTimeOptionsBase): Plugin[] {
+  const {
+    authToken,
+    bundleSizeOptimizations,
+    debug,
+    errorHandler,
+    headers,
+    org,
+    project,
+    release,
+    sentryUrl,
+    silent,
+    sourcemaps,
+    telemetry,
+  } = options;
+
+  // defer resolving the filesToDeleteAfterUpload until we got access to the Vite config
+  let resolveFilesToDeleteAfterUpload: ((value: FilesToDeleteAfterUpload) => void) | undefined;
+  const filesToDeleteAfterUploadPromise = new Promise<FilesToDeleteAfterUpload>(resolve => {
+    resolveFilesToDeleteAfterUpload = resolve;
+  });
+
+  const configPlugin: Plugin = {
+    name: 'sentry-tanstackstart-files-to-delete-after-upload-plugin',
+    apply: 'build',
+    enforce: 'post',
+    config(config) {
+      const userFilesToDelete = sourcemaps?.filesToDeleteAfterUpload;
+
+      // Only auto-delete source maps if the user didn't configure sourcemaps at all
+      if (typeof userFilesToDelete === 'undefined' && typeof config.build?.sourcemap === 'undefined') {
+        if (debug) {
+          // eslint-disable-next-line no-console
+          console.log(
+            '[Sentry] Automatically setting `sourcemaps.filesToDeleteAfterUpload: ["./**/*.map"]` to delete generated source maps after they were uploaded to Sentry.',
+          );
+        }
+        resolveFilesToDeleteAfterUpload?.(['./**/*.map']);
+      } else {
+        resolveFilesToDeleteAfterUpload?.(userFilesToDelete);
+      }
+    },
+  };
+
+  const sentryPlugins = sentryVitePlugin({
+    authToken: authToken ?? process.env.SENTRY_AUTH_TOKEN,
+    bundleSizeOptimizations: bundleSizeOptimizations ?? undefined,
+    debug: debug ?? false,
+    errorHandler,
+    headers,
+    org: org ?? process.env.SENTRY_ORG,
+    project: project ?? process.env.SENTRY_PROJECT,
+    release,
+    silent,
+    sourcemaps: {
+      assets: sourcemaps?.assets,
+      disable: sourcemaps?.disable,
+      ignore: sourcemaps?.ignore,
+      filesToDeleteAfterUpload: filesToDeleteAfterUploadPromise,
+    },
+    telemetry: telemetry ?? true,
+    url: sentryUrl,
+    _metaOptions: {
+      telemetry: {
+        metaFramework: 'tanstackstart-react',
+      },
+    },
+  });
+
+  return [configPlugin, ...sentryPlugins];
+}
+
+/**
+ * A Sentry plugin for TanStack Start React to enable "hidden" source maps if they are unset.
+ */
+export function makeEnableSourceMapsVitePlugin(options: BuildTimeOptionsBase): 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?: BuildTimeOptionsBase,
+): boolean | 'inline' | 'hidden' {
+  viteConfig.build = viteConfig.build || {};
+
+  const viteUserSourceMapSetting = viteConfig.build?.sourcemap;
+  const settingKey = 'vite.build.sourcemap';
+  const debug = sentryPluginOptions?.debug;
+
+  // Respect user source map setting if it is explicitly set
+  if (viteUserSourceMapSetting === false) {
+    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.');
+    }
+
+    return viteUserSourceMapSetting;
+  } else if (viteUserSourceMapSetting && ['hidden', 'inline', true].includes(viteUserSourceMapSetting)) {
+    if (debug) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[Sentry] We discovered \`${settingKey}\` is set to \`${viteUserSourceMapSetting.toString()}\`. Sentry will keep this source map setting.`,
+      );
+    }
+
+    return viteUserSourceMapSetting;
+  }
+
+  // If the user did not specify a source map setting, we enable 'hidden' by default
+  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 'hidden';
+}

packages/tanstackstart-react/test/vite/sentryTanstackStart.test.ts

@@ -0,0 +1,82 @@
+import type { Plugin } from 'vite';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { sentryTanstackStart } from '../../src/vite/sentryTanstackStart';
+
+const mockSourceMapsConfigPlugin: Plugin = {
+  name: 'sentry-tanstackstart-files-to-delete-after-upload-plugin',
+  apply: 'build',
+  enforce: 'pre',
+  config: vi.fn(),
+};
+
+const mockSentryVitePlugin: Plugin = {
+  name: 'sentry-vite-debug-id-upload-plugin',
+  writeBundle: vi.fn(),
+};
+
+const mockEnableSourceMapsPlugin: Plugin = {
+  name: 'sentry-tanstackstart-react-source-maps',
+  apply: 'build',
+  enforce: 'post',
+  config: vi.fn(),
+};
+
+vi.mock('../../src/vite/sourceMaps', () => ({
+  makeAddSentryVitePlugin: vi.fn(() => [mockSourceMapsConfigPlugin, mockSentryVitePlugin]),
+  makeEnableSourceMapsVitePlugin: vi.fn(() => [mockEnableSourceMapsPlugin]),
+}));
+
+describe('sentryTanstackStart()', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env.NODE_ENV = 'production';
+  });
+
+  afterEach(() => {
+    process.env.NODE_ENV = 'production';
+  });
+
+  it('returns plugins in production mode', () => {
+    const plugins = sentryTanstackStart({ org: 'test-org' });
+
+    expect(plugins).toEqual([mockSourceMapsConfigPlugin, mockSentryVitePlugin, mockEnableSourceMapsPlugin]);
+  });
+
+  it('returns no plugins in development mode', () => {
+    process.env.NODE_ENV = 'development';
+
+    const plugins = sentryTanstackStart({ org: 'test-org' });
+
+    expect(plugins).toEqual([]);
+  });
+
+  it('returns Sentry Vite plugins but not enable source maps plugin when sourcemaps.disable is true', () => {
+    const plugins = sentryTanstackStart({
+      sourcemaps: { disable: true },
+    });
+
+    expect(plugins).toEqual([mockSourceMapsConfigPlugin, mockSentryVitePlugin]);
+  });
+
+  it('returns Sentry Vite plugins but not enable source maps plugin when sourcemaps.disable is "disable-upload"', () => {
+    const plugins = sentryTanstackStart({
+      sourcemaps: { disable: 'disable-upload' },
+    });
+
+    expect(plugins).toEqual([mockSourceMapsConfigPlugin, mockSentryVitePlugin]);
+  });
+
+  it('returns Sentry Vite plugins and enable source maps plugin when sourcemaps.disable is false', () => {
+    const plugins = sentryTanstackStart({
+      sourcemaps: { disable: false },
+    });
+
+    expect(plugins).toEqual([mockSourceMapsConfigPlugin, mockSentryVitePlugin, mockEnableSourceMapsPlugin]);
+  });
+
+  it('returns Sentry Vite Plugins and enable source maps plugin by default when sourcemaps is not specified', () => {
+    const plugins = sentryTanstackStart({});
+
+    expect(plugins).toEqual([mockSourceMapsConfigPlugin, mockSentryVitePlugin, mockEnableSourceMapsPlugin]);
+  });
+});