feat(tanstackstart-react): Add file exclude to configure middleware auto-instrumentation

Author: nicohrubec

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

@@ -1,8 +1,10 @@
+import { stringMatchesSomePattern } from '@sentry/core';
 import type { Plugin } from 'vite';
 
 type AutoInstrumentMiddlewareOptions = {
   enabled?: boolean;
   debug?: boolean;
+  exclude?: Array<string | RegExp>;
 };
 
 type WrapResult = {
@@ -64,13 +66,32 @@ export function wrapServerFnMiddleware(code: string, id: string, debug: boolean)
   return wrapMiddlewareArrays(code, id, debug, /(\.middleware\s*\()\s*\[([^\]]*)\]\s*\)/g);
 }
 
+/**
+ * Checks if a file should be skipped from auto-instrumentation based on exclude patterns.
+ */
+function shouldSkipFile(id: string, exclude: Array<string | RegExp> | undefined, debug: boolean): boolean {
+  if (!exclude || exclude.length === 0) {
+    return false;
+  }
+
+  if (stringMatchesSomePattern(id, exclude)) {
+    if (debug) {
+      // eslint-disable-next-line no-console
+      console.log(`[Sentry] Skipping auto-instrumentation for excluded file: ${id}`);
+    }
+    return true;
+  }
+
+  return false;
+}
+
 /**
  * A Vite plugin that automatically instruments TanStack Start middlewares:
  * - `requestMiddleware` and `functionMiddleware` arrays in `createStart()`
  * - `middleware` arrays in `createFileRoute()` route definitions
  */
 export function makeAutoInstrumentMiddlewarePlugin(options: AutoInstrumentMiddlewareOptions = {}): Plugin {
-  const { enabled = true, debug = false } = options;
+  const { enabled = true, debug = false, exclude } = options;
 
   return {
     name: 'sentry-tanstack-middleware-auto-instrument',
@@ -86,6 +107,11 @@ export function makeAutoInstrumentMiddlewarePlugin(options: AutoInstrumentMiddle
         return null;
       }
 
+      // Skip if file matches exclude patterns
+      if (shouldSkipFile(id, exclude, debug)) {
+        return null;
+      }
+
       // Detect file types that should be instrumented
       const isStartFile = id.includes('start') && code.includes('createStart(');
       const isRouteFile = code.includes('createFileRoute(') && /middleware\s*:\s*\[/.test(code);

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

@@ -8,17 +8,34 @@ import { makeAddSentryVitePlugin, makeEnableSourceMapsVitePlugin } from './sourc
  */
 export interface SentryTanstackStartOptions extends BuildTimeOptionsBase {
   /**
-   * If this flag is `true`, the Sentry plugins will automatically instrument TanStack Start middlewares.
+   * Configure automatic middleware instrumentation.
    *
-   * This wraps global middlewares (`requestMiddleware` and `functionMiddleware`) in `createStart()` with Sentry
-   * instrumentation to capture performance data.
+   * - Set to `false` to disable automatic middleware instrumentation entirely.
+   * - Set to `true` (default) to enable for all middleware files.
+   * - Set to an object with `exclude` to enable but exclude specific files.
    *
-   * Set to `false` to disable automatic middleware instrumentation if you prefer to wrap middlewares manually
-   * using `wrapMiddlewaresWithSentry`.
+   * The `exclude` option takes an array of strings or regular expressions matched
+   * against the full file path. String patterns match as substrings.
    *
    * @default true
+   *
+   * @example
+   * // Disable completely
+   * sentryTanstackStart({ autoInstrumentMiddleware: false })
+   *
+   * @example
+   * // Enable with exclusions
+   * sentryTanstackStart({
+   *   autoInstrumentMiddleware: {
+   *     exclude: ['/routes/admin/', /\.test\.ts$/],
+   *   },
+   * })
    */
-  autoInstrumentMiddleware?: boolean;
+  autoInstrumentMiddleware?:
+    | boolean
+    | {
+        exclude?: Array<string | RegExp>;
+      };
 }
 
 /**
@@ -54,8 +71,18 @@ export function sentryTanstackStart(options: SentryTanstackStartOptions = {}): P
   const plugins: Plugin[] = [...makeAddSentryVitePlugin(options)];
 
   // middleware auto-instrumentation
-  if (options.autoInstrumentMiddleware !== false) {
-    plugins.push(makeAutoInstrumentMiddlewarePlugin({ enabled: true, debug: options.debug }));
+  const autoInstrumentConfig = options.autoInstrumentMiddleware;
+  const isDisabled = autoInstrumentConfig === false;
+  const excludePatterns = typeof autoInstrumentConfig === 'object' ? autoInstrumentConfig.exclude : undefined;
+
+  if (!isDisabled) {
+    plugins.push(
+      makeAutoInstrumentMiddlewarePlugin({
+        enabled: true,
+        debug: options.debug,
+        exclude: excludePatterns,
+      }),
+    );
   }
 
   // source maps

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

@@ -445,6 +445,97 @@ describe('addSentryImport', () => {
   });
 });
 
+describe('exclude option', () => {
+  const createStartFile = `
+import { createStart } from '@tanstack/react-start';
+createStart(() => ({ requestMiddleware: [authMiddleware] }));
+`;
+
+  it('excludes files matching string pattern (substring match)', () => {
+    const plugin = makeAutoInstrumentMiddlewarePlugin({
+      exclude: ['/routes/admin/'],
+    }) as PluginWithTransform;
+
+    const result = plugin.transform(createStartFile, '/app/routes/admin/start.ts');
+
+    expect(result).toBeNull();
+  });
+
+  it('excludes files matching regex pattern', () => {
+    const plugin = makeAutoInstrumentMiddlewarePlugin({
+      exclude: [/\.test\.ts$/],
+    }) as PluginWithTransform;
+
+    const result = plugin.transform(createStartFile, '/app/start.test.ts');
+
+    expect(result).toBeNull();
+  });
+
+  it('excludes files matching any of multiple patterns', () => {
+    const plugin = makeAutoInstrumentMiddlewarePlugin({
+      exclude: ['/routes/admin/', /\.test\.ts$/],
+    }) as PluginWithTransform;
+
+    // String pattern match
+    const result1 = plugin.transform(createStartFile, '/app/routes/admin/start.ts');
+    expect(result1).toBeNull();
+
+    // Regex pattern match
+    const result2 = plugin.transform(createStartFile, '/app/start.test.ts');
+    expect(result2).toBeNull();
+  });
+
+  it('instruments files not matching exclude patterns', () => {
+    const plugin = makeAutoInstrumentMiddlewarePlugin({
+      exclude: ['/routes/admin/', /\.test\.ts$/],
+    }) as PluginWithTransform;
+
+    const result = plugin.transform(createStartFile, '/app/start.ts');
+
+    expect(result).not.toBeNull();
+    expect(result!.code).toContain('wrapMiddlewaresWithSentry');
+  });
+
+  it('instruments all files when exclude is empty array', () => {
+    const plugin = makeAutoInstrumentMiddlewarePlugin({
+      exclude: [],
+    }) as PluginWithTransform;
+
+    const result = plugin.transform(createStartFile, '/app/start.ts');
+
+    expect(result).not.toBeNull();
+    expect(result!.code).toContain('wrapMiddlewaresWithSentry');
+  });
+
+  it('instruments all files when exclude is undefined', () => {
+    const plugin = makeAutoInstrumentMiddlewarePlugin({
+      exclude: undefined,
+    }) as PluginWithTransform;
+
+    const result = plugin.transform(createStartFile, '/app/start.ts');
+
+    expect(result).not.toBeNull();
+    expect(result!.code).toContain('wrapMiddlewaresWithSentry');
+  });
+
+  it('logs debug message when file is excluded', () => {
+    const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    const plugin = makeAutoInstrumentMiddlewarePlugin({
+      debug: true,
+      exclude: ['/routes/admin/'],
+    }) as PluginWithTransform;
+
+    plugin.transform(createStartFile, '/app/routes/admin/start.ts');
+
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Skipping auto-instrumentation for excluded file'),
+    );
+
+    consoleLogSpy.mockRestore();
+  });
+});
+
 describe('arrayToObjectShorthand', () => {
   it('converts single identifier', () => {
     expect(arrayToObjectShorthand('foo')).toBe('{ foo }');

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

@@ -118,13 +118,48 @@ describe('sentryTanstackStart()', () => {
     it('passes correct options to makeAutoInstrumentMiddlewarePlugin', () => {
       sentryTanstackStart({ debug: true, sourcemaps: { disable: true } });
 
-      expect(makeAutoInstrumentMiddlewarePlugin).toHaveBeenCalledWith({ enabled: true, debug: true });
+      expect(makeAutoInstrumentMiddlewarePlugin).toHaveBeenCalledWith({
+        enabled: true,
+        debug: true,
+        exclude: undefined,
+      });
     });
 
     it('passes debug: undefined when not specified', () => {
       sentryTanstackStart({ sourcemaps: { disable: true } });
 
-      expect(makeAutoInstrumentMiddlewarePlugin).toHaveBeenCalledWith({ enabled: true, debug: undefined });
+      expect(makeAutoInstrumentMiddlewarePlugin).toHaveBeenCalledWith({
+        enabled: true,
+        debug: undefined,
+        exclude: undefined,
+      });
+    });
+
+    it('passes exclude patterns when autoInstrumentMiddleware is an object', () => {
+      const excludePatterns = ['/routes/admin/', /\.test\.ts$/];
+      sentryTanstackStart({
+        autoInstrumentMiddleware: { exclude: excludePatterns },
+        sourcemaps: { disable: true },
+      });
+
+      expect(makeAutoInstrumentMiddlewarePlugin).toHaveBeenCalledWith({
+        enabled: true,
+        debug: undefined,
+        exclude: excludePatterns,
+      });
+    });
+
+    it('passes exclude: undefined when autoInstrumentMiddleware is true', () => {
+      sentryTanstackStart({
+        autoInstrumentMiddleware: true,
+        sourcemaps: { disable: true },
+      });
+
+      expect(makeAutoInstrumentMiddlewarePlugin).toHaveBeenCalledWith({
+        enabled: true,
+        debug: undefined,
+        exclude: undefined,
+      });
     });
   });
 });