feat(tanstackstart-react): Add global sentry exception middlewares

CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(tanstackstart-react): Add global sentry exception middlewares ([#19330](https://github.com/getsentry/sentry-javascript/pull/19330))**
+
+ The `sentryGlobalRequestMiddleware` and `sentryGlobalFunctionMiddleware` global middlewares capture unhandled exceptions thrown in TanStack Start API routes and server functions. Add them as the first entries in the `requestMiddleware` and `functionMiddleware` arrays of `createStart()`:
+
+ ```ts
+ import { createStart } from '@tanstack/react-start/server';
+ import { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from '@sentry/tanstackstart-react/server';
+
+ export default createStart({
+ requestMiddleware: [sentryGlobalRequestMiddleware, myRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, myFunctionMiddleware],
+ });
+ ```
+
 ### Important Changes
 
 - fix(node-core): Reduce bundle size by removing apm-js-collab and requiring pino >= 9.10 ([#18631](https://github.com/getsentry/sentry-javascript/pull/18631))

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.error.ts

@@ -1,16 +1,10 @@
-import * as Sentry from '@sentry/tanstackstart-react';
 import { createFileRoute } from '@tanstack/react-router';
 
 export const Route = createFileRoute('/api/error')({
  server: {
  handlers: {
  GET: async () => {
- try {
- throw new Error('Sentry API Route Test Error');
- } catch (error) {
- Sentry.captureException(error);
- throw error;
- }
+ throw new Error('Sentry API Route Test Error');
  },
  },
  },

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.flush.ts

@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { flush } from '@sentry/tanstackstart-react';
+
+export const Route = createFileRoute('/api/flush')({
+ server: {
+ handlers: {
+ GET: async () => {
+ await flush();
+ return new Response('ok');
+ },
+ },
+ },
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/ssr-error.tsx

@@ -0,0 +1,8 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/ssr-error')({
+ loader: () => {
+ throw new Error('Sentry SSR Test Error');
+ },
+ component: () => <div>SSR Error Page</div>,
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/start.ts

@@ -1,10 +1,11 @@
+import { sentryGlobalFunctionMiddleware, sentryGlobalRequestMiddleware } from '@sentry/tanstackstart-react';
 import { createStart } from '@tanstack/react-start';
 // NOTE: These are NOT wrapped - auto-instrumentation via the Vite plugin will wrap them
-import { globalRequestMiddleware, globalFunctionMiddleware } from './middleware';
+import { globalFunctionMiddleware, globalRequestMiddleware } from './middleware';
 
 export const startInstance = createStart(() => {
  return {
- requestMiddleware: [globalRequestMiddleware],
- functionMiddleware: [globalFunctionMiddleware],
+ requestMiddleware: [sentryGlobalRequestMiddleware, globalRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, globalFunctionMiddleware],
  };
 });

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

@@ -1,5 +1,5 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Sends client-side error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
@@ -51,17 +51,18 @@ test('Sends server-side function error to Sentry with auto-instrumentation', asy
  type: 'Error',
  value: 'Sentry Server Function Test Error',
  mechanism: {
+ type: 'auto.middleware.tanstackstart.server_function',
  handled: false,
  },
  },
  ],
  },
  });
 
- expect(errorEvent.transaction).toBe('/');
+ expect(errorEvent.transaction).toEqual(expect.stringContaining('GET /_serverFn/'));
 });
 
-test('Sends API route error to Sentry if manually instrumented', async ({ page }) => {
+test('Sends API route error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
  return errorEvent?.exception?.values?.[0]?.value === 'Sentry API Route Test Error';
  });
@@ -81,7 +82,8 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
  type: 'Error',
  value: 'Sentry API Route Test Error',
  mechanism: {
- handled: true,
+ type: 'auto.middleware.tanstackstart.request',
+ handled: false,
  },
  },
  ],
@@ -90,3 +92,28 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
 
  expect(errorEvent.transaction).toBe('GET /api/error');
 });
+
+// the sentry global middleware does not capture errors from SSR loader errors since they are serialized before they reach the middleware layer
+// this test verifies that the error is in fact not sent to Sentry
+test('Does not send SSR loader error to Sentry', async ({ baseURL, page }) => {
+ let errorEventOccurred = false;
+
+ waitForError('tanstackstart-react', event => {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Sentry SSR Test Error') {
+ errorEventOccurred = true;
+ }
+ return event?.transaction === 'GET /ssr-error';
+ });
+
+ const transactionEventPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.transaction === 'GET /ssr-error';
+ });
+
+ await page.goto('/ssr-error');
+
+ await transactionEventPromise;
+
+ await (await fetch(`${baseURL}/api/flush`)).text();
+
+ expect(errorEventOccurred).toBe(false);
+});

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

@@ -14,3 +14,15 @@ export { init } from './sdk';
 export function wrapMiddlewaresWithSentry<T extends TanStackMiddlewareBase>(middlewares: Record<string, T>): T[] {
  return Object.values(middlewares);
 }
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };

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

@@ -1,5 +1,8 @@
 export type TanStackMiddlewareBase = {
- options?: { server?: (...args: unknown[]) => unknown };
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ '~types': any;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ options: { server?: (...args: any[]) => any };
 };
 
 export type MiddlewareWrapperOptions = {

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

@@ -37,3 +37,6 @@ export declare const statsigIntegration: typeof clientSdk.statsigIntegration;
 export declare const unleashIntegration: typeof clientSdk.unleashIntegration;
 
 export declare const wrapMiddlewaresWithSentry: typeof serverSdk.wrapMiddlewaresWithSentry;
+
+export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
+export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;

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

@@ -0,0 +1,46 @@
+import { addNonEnumerableProperty, captureException } from '@sentry/core';
+import type { TanStackMiddlewareBase } from '../common/types';
+import { SENTRY_INTERNAL } from './middleware';
+
+function createSentryMiddlewareHandler(mechanismType: string) {
+ return async function sentryMiddlewareHandler({ next }: { next: () => Promise<unknown> }): Promise<unknown> {
+ try {
+ return await next();
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: mechanismType, handled: false },
+ });
+ throw e;
+ }
+ };
+}
+
+/**
+ * Global request middleware that captures errors from API route requests.
+ * Should be added as the first entry in the `requestMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.request') as (...args: any[]) => any,
+ },
+};
+
+/**
+ * Global function middleware that captures errors from server function invocations.
+ * Should be added as the first entry in the `functionMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (...args: any[]) => any,
+ },
+};
+
+// Mark as internal so the Vite auto-instrumentation plugin skips these middleware
+addNonEnumerableProperty(sentryGlobalRequestMiddleware, SENTRY_INTERNAL, true);
+addNonEnumerableProperty(sentryGlobalFunctionMiddleware, SENTRY_INTERNAL, true);

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

@@ -6,6 +6,7 @@ export * from '@sentry/node';
 export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
+export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
 
 /**
  * A passthrough error boundary for the server that doesn't depend on any react. Error boundaries don't catch SSR errors

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

@@ -5,6 +5,7 @@ import type { MiddlewareWrapperOptions, TanStackMiddlewareBase } from '../common
 import { getMiddlewareSpanOptions } from './utils';
 
 const SENTRY_WRAPPED = '__SENTRY_WRAPPED__';
+export const SENTRY_INTERNAL = '__SENTRY_INTERNAL__';
 
 /**
  * Creates a proxy for the next function that ends the current span and restores the parent span.
@@ -39,8 +40,11 @@ function wrapMiddlewareWithSentry<T extends TanStackMiddlewareBase>(
  middleware: T,
  options: MiddlewareWrapperOptions,
 ): T {
- if ((middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED]) {
- // already instrumented
+ if (
+ (middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED] ||
+ (middleware as TanStackMiddlewareBase & { [SENTRY_INTERNAL]?: boolean })[SENTRY_INTERNAL]
+ ) {
+ // already instrumented or internal Sentry middleware
  return middleware;
  }
 

packages/tanstackstart-react/test/server/globalMiddleware.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const captureExceptionSpy = vi.fn();
+
+vi.mock('@sentry/core', async importOriginal => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ captureException: (...args: unknown[]) => captureExceptionSpy(...args),
+ };
+});
+
+// Import after mocks are set up
+const { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } =
+ await import('../../src/server/globalMiddleware');
+
+describe('sentryGlobalRequestMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.request', handled: false },
+ });
+ });
+
+ it('does not capture error when next() succeeds', async () => {
+ const next = vi.fn().mockResolvedValue('success');
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+ const result = await serverFn({ next });
+
+ expect(result).toBe('success');
+ expect(captureExceptionSpy).not.toHaveBeenCalled();
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalRequestMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});
+
+describe('sentryGlobalFunctionMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalFunctionMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.server_function', handled: false },
+ });
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalFunctionMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});

CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(tanstackstart-react): Add global sentry exception middlewares ([#19330](https://github.com/getsentry/sentry-javascript/pull/19330))**
+
+ The `sentryGlobalRequestMiddleware` and `sentryGlobalFunctionMiddleware` global middlewares capture unhandled exceptions thrown in TanStack Start API routes and server functions. Add them as the first entries in the `requestMiddleware` and `functionMiddleware` arrays of `createStart()`:
+
+ ```ts
+ import { createStart } from '@tanstack/react-start/server';
+ import { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from '@sentry/tanstackstart-react/server';
+
+ export default createStart({
+ requestMiddleware: [sentryGlobalRequestMiddleware, myRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, myFunctionMiddleware],
+ });
+ ```
+
 ### Important Changes
 
 - fix(node-core): Reduce bundle size by removing apm-js-collab and requiring pino >= 9.10 ([#18631](https://github.com/getsentry/sentry-javascript/pull/18631))

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.error.ts

@@ -1,16 +1,10 @@
-import * as Sentry from '@sentry/tanstackstart-react';
 import { createFileRoute } from '@tanstack/react-router';
 
 export const Route = createFileRoute('/api/error')({
  server: {
  handlers: {
  GET: async () => {
- try {
- throw new Error('Sentry API Route Test Error');
- } catch (error) {
- Sentry.captureException(error);
- throw error;
- }
+ throw new Error('Sentry API Route Test Error');
  },
  },
  },

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.flush.ts

@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { flush } from '@sentry/tanstackstart-react';
+
+export const Route = createFileRoute('/api/flush')({
+ server: {
+ handlers: {
+ GET: async () => {
+ await flush();
+ return new Response('ok');
+ },
+ },
+ },
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/ssr-error.tsx

@@ -0,0 +1,8 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/ssr-error')({
+ loader: () => {
+ throw new Error('Sentry SSR Test Error');
+ },
+ component: () => <div>SSR Error Page</div>,
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/start.ts

@@ -1,10 +1,11 @@
+import { sentryGlobalFunctionMiddleware, sentryGlobalRequestMiddleware } from '@sentry/tanstackstart-react';
 import { createStart } from '@tanstack/react-start';
 // NOTE: These are NOT wrapped - auto-instrumentation via the Vite plugin will wrap them
-import { globalRequestMiddleware, globalFunctionMiddleware } from './middleware';
+import { globalFunctionMiddleware, globalRequestMiddleware } from './middleware';
 
 export const startInstance = createStart(() => {
  return {
- requestMiddleware: [globalRequestMiddleware],
- functionMiddleware: [globalFunctionMiddleware],
+ requestMiddleware: [sentryGlobalRequestMiddleware, globalRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, globalFunctionMiddleware],
  };
 });

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

@@ -1,5 +1,5 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Sends client-side error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
@@ -51,17 +51,18 @@ test('Sends server-side function error to Sentry with auto-instrumentation', asy
  type: 'Error',
  value: 'Sentry Server Function Test Error',
  mechanism: {
+ type: 'auto.middleware.tanstackstart.server_function',
  handled: false,
  },
  },
  ],
  },
  });
 
- expect(errorEvent.transaction).toBe('/');
+ expect(errorEvent.transaction).toEqual(expect.stringContaining('GET /_serverFn/'));
 });
 
-test('Sends API route error to Sentry if manually instrumented', async ({ page }) => {
+test('Sends API route error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
  return errorEvent?.exception?.values?.[0]?.value === 'Sentry API Route Test Error';
  });
@@ -81,7 +82,8 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
  type: 'Error',
  value: 'Sentry API Route Test Error',
  mechanism: {
- handled: true,
+ type: 'auto.middleware.tanstackstart.request',
+ handled: false,
  },
  },
  ],
@@ -90,3 +92,28 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
 
  expect(errorEvent.transaction).toBe('GET /api/error');
 });
+
+// the sentry global middleware does not capture errors from SSR loader errors since they are serialized before they reach the middleware layer
+// this test verifies that the error is in fact not sent to Sentry
+test('Does not send SSR loader error to Sentry', async ({ baseURL, page }) => {
+ let errorEventOccurred = false;
+
+ waitForError('tanstackstart-react', event => {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Sentry SSR Test Error') {
+ errorEventOccurred = true;
+ }
+ return event?.transaction === 'GET /ssr-error';
+ });
+
+ const transactionEventPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.transaction === 'GET /ssr-error';
+ });
+
+ await page.goto('/ssr-error');
+
+ await transactionEventPromise;
+
+ await (await fetch(`${baseURL}/api/flush`)).text();
+
+ expect(errorEventOccurred).toBe(false);
+});

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

@@ -14,3 +14,15 @@ export { init } from './sdk';
 export function wrapMiddlewaresWithSentry<T extends TanStackMiddlewareBase>(middlewares: Record<string, T>): T[] {
  return Object.values(middlewares);
 }
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };

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

@@ -1,5 +1,8 @@
 export type TanStackMiddlewareBase = {
- options?: { server?: (...args: unknown[]) => unknown };
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ '~types': any;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ options: { server?: (...args: any[]) => any };
 };
 
 export type MiddlewareWrapperOptions = {

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

@@ -37,3 +37,6 @@ export declare const statsigIntegration: typeof clientSdk.statsigIntegration;
 export declare const unleashIntegration: typeof clientSdk.unleashIntegration;
 
 export declare const wrapMiddlewaresWithSentry: typeof serverSdk.wrapMiddlewaresWithSentry;
+
+export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
+export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;

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

@@ -0,0 +1,46 @@
+import { addNonEnumerableProperty, captureException } from '@sentry/core';
+import type { TanStackMiddlewareBase } from '../common/types';
+import { SENTRY_INTERNAL } from './middleware';
+
+function createSentryMiddlewareHandler(mechanismType: string) {
+ return async function sentryMiddlewareHandler({ next }: { next: () => Promise<unknown> }): Promise<unknown> {
+ try {
+ return await next();
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: mechanismType, handled: false },
+ });
+ throw e;
+ }
+ };
+}
+
+/**
+ * Global request middleware that captures errors from API route requests.
+ * Should be added as the first entry in the `requestMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.request') as (...args: any[]) => any,
+ },
+};
+
+/**
+ * Global function middleware that captures errors from server function invocations.
+ * Should be added as the first entry in the `functionMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (...args: any[]) => any,
+ },
+};
+
+// Mark as internal so the Vite auto-instrumentation plugin skips these middleware
+addNonEnumerableProperty(sentryGlobalRequestMiddleware, SENTRY_INTERNAL, true);
+addNonEnumerableProperty(sentryGlobalFunctionMiddleware, SENTRY_INTERNAL, true);

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

@@ -6,6 +6,7 @@ export * from '@sentry/node';
 export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
+export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
 
 /**
  * A passthrough error boundary for the server that doesn't depend on any react. Error boundaries don't catch SSR errors

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

@@ -5,6 +5,7 @@ import type { MiddlewareWrapperOptions, TanStackMiddlewareBase } from '../common
 import { getMiddlewareSpanOptions } from './utils';
 
 const SENTRY_WRAPPED = '__SENTRY_WRAPPED__';
+export const SENTRY_INTERNAL = '__SENTRY_INTERNAL__';
 
 /**
  * Creates a proxy for the next function that ends the current span and restores the parent span.
@@ -39,8 +40,11 @@ function wrapMiddlewareWithSentry<T extends TanStackMiddlewareBase>(
  middleware: T,
  options: MiddlewareWrapperOptions,
 ): T {
- if ((middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED]) {
- // already instrumented
+ if (
+ (middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED] ||
+ (middleware as TanStackMiddlewareBase & { [SENTRY_INTERNAL]?: boolean })[SENTRY_INTERNAL]
+ ) {
+ // already instrumented or internal Sentry middleware
  return middleware;
  }
 

packages/tanstackstart-react/test/server/globalMiddleware.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const captureExceptionSpy = vi.fn();
+
+vi.mock('@sentry/core', async importOriginal => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ captureException: (...args: unknown[]) => captureExceptionSpy(...args),
+ };
+});
+
+// Import after mocks are set up
+const { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } =
+ await import('../../src/server/globalMiddleware');
+
+describe('sentryGlobalRequestMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.request', handled: false },
+ });
+ });
+
+ it('does not capture error when next() succeeds', async () => {
+ const next = vi.fn().mockResolvedValue('success');
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+ const result = await serverFn({ next });
+
+ expect(result).toBe('success');
+ expect(captureExceptionSpy).not.toHaveBeenCalled();
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalRequestMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});
+
+describe('sentryGlobalFunctionMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalFunctionMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.server_function', handled: false },
+ });
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalFunctionMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});

CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(tanstackstart-react): Add global sentry exception middlewares ([#19330](https://github.com/getsentry/sentry-javascript/pull/19330))**
+
+ The `sentryGlobalRequestMiddleware` and `sentryGlobalFunctionMiddleware` global middlewares capture unhandled exceptions thrown in TanStack Start API routes and server functions. Add them as the first entries in the `requestMiddleware` and `functionMiddleware` arrays of `createStart()`:
+
+ ```ts
+ import { createStart } from '@tanstack/react-start/server';
+ import { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from '@sentry/tanstackstart-react/server';
+
+ export default createStart({
+ requestMiddleware: [sentryGlobalRequestMiddleware, myRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, myFunctionMiddleware],
+ });
+ ```
+
 ### Important Changes
 
 - fix(node-core): Reduce bundle size by removing apm-js-collab and requiring pino >= 9.10 ([#18631](https://github.com/getsentry/sentry-javascript/pull/18631))

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.error.ts

@@ -1,16 +1,10 @@
-import * as Sentry from '@sentry/tanstackstart-react';
 import { createFileRoute } from '@tanstack/react-router';
 
 export const Route = createFileRoute('/api/error')({
  server: {
  handlers: {
  GET: async () => {
- try {
- throw new Error('Sentry API Route Test Error');
- } catch (error) {
- Sentry.captureException(error);
- throw error;
- }
+ throw new Error('Sentry API Route Test Error');
  },
  },
  },

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.flush.ts

@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { flush } from '@sentry/tanstackstart-react';
+
+export const Route = createFileRoute('/api/flush')({
+ server: {
+ handlers: {
+ GET: async () => {
+ await flush();
+ return new Response('ok');
+ },
+ },
+ },
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/ssr-error.tsx

@@ -0,0 +1,8 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/ssr-error')({
+ loader: () => {
+ throw new Error('Sentry SSR Test Error');
+ },
+ component: () => <div>SSR Error Page</div>,
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/start.ts

@@ -1,10 +1,11 @@
+import { sentryGlobalFunctionMiddleware, sentryGlobalRequestMiddleware } from '@sentry/tanstackstart-react';
 import { createStart } from '@tanstack/react-start';
 // NOTE: These are NOT wrapped - auto-instrumentation via the Vite plugin will wrap them
-import { globalRequestMiddleware, globalFunctionMiddleware } from './middleware';
+import { globalFunctionMiddleware, globalRequestMiddleware } from './middleware';
 
 export const startInstance = createStart(() => {
  return {
- requestMiddleware: [globalRequestMiddleware],
- functionMiddleware: [globalFunctionMiddleware],
+ requestMiddleware: [sentryGlobalRequestMiddleware, globalRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, globalFunctionMiddleware],
  };
 });

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

@@ -1,5 +1,5 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Sends client-side error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
@@ -51,17 +51,18 @@ test('Sends server-side function error to Sentry with auto-instrumentation', asy
  type: 'Error',
  value: 'Sentry Server Function Test Error',
  mechanism: {
+ type: 'auto.middleware.tanstackstart.server_function',
  handled: false,
  },
  },
  ],
  },
  });
 
- expect(errorEvent.transaction).toBe('/');
+ expect(errorEvent.transaction).toEqual(expect.stringContaining('GET /_serverFn/'));
 });
 
-test('Sends API route error to Sentry if manually instrumented', async ({ page }) => {
+test('Sends API route error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
  return errorEvent?.exception?.values?.[0]?.value === 'Sentry API Route Test Error';
  });
@@ -81,7 +82,8 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
  type: 'Error',
  value: 'Sentry API Route Test Error',
  mechanism: {
- handled: true,
+ type: 'auto.middleware.tanstackstart.request',
+ handled: false,
  },
  },
  ],
@@ -90,3 +92,28 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
 
  expect(errorEvent.transaction).toBe('GET /api/error');
 });
+
+// the sentry global middleware does not capture errors from SSR loader errors since they are serialized before they reach the middleware layer
+// this test verifies that the error is in fact not sent to Sentry
+test('Does not send SSR loader error to Sentry', async ({ baseURL, page }) => {
+ let errorEventOccurred = false;
+
+ waitForError('tanstackstart-react', event => {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Sentry SSR Test Error') {
+ errorEventOccurred = true;
+ }
+ return event?.transaction === 'GET /ssr-error';
+ });
+
+ const transactionEventPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.transaction === 'GET /ssr-error';
+ });
+
+ await page.goto('/ssr-error');
+
+ await transactionEventPromise;
+
+ await (await fetch(`${baseURL}/api/flush`)).text();
+
+ expect(errorEventOccurred).toBe(false);
+});

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

@@ -14,3 +14,15 @@ export { init } from './sdk';
 export function wrapMiddlewaresWithSentry<T extends TanStackMiddlewareBase>(middlewares: Record<string, T>): T[] {
  return Object.values(middlewares);
 }
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };

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

@@ -1,5 +1,8 @@
 export type TanStackMiddlewareBase = {
- options?: { server?: (...args: unknown[]) => unknown };
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ '~types': any;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ options: { server?: (...args: any[]) => any };
 };
 
 export type MiddlewareWrapperOptions = {

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

@@ -37,3 +37,6 @@ export declare const statsigIntegration: typeof clientSdk.statsigIntegration;
 export declare const unleashIntegration: typeof clientSdk.unleashIntegration;
 
 export declare const wrapMiddlewaresWithSentry: typeof serverSdk.wrapMiddlewaresWithSentry;
+
+export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
+export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;

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

@@ -0,0 +1,46 @@
+import { addNonEnumerableProperty, captureException } from '@sentry/core';
+import type { TanStackMiddlewareBase } from '../common/types';
+import { SENTRY_INTERNAL } from './middleware';
+
+function createSentryMiddlewareHandler(mechanismType: string) {
+ return async function sentryMiddlewareHandler({ next }: { next: () => Promise<unknown> }): Promise<unknown> {
+ try {
+ return await next();
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: mechanismType, handled: false },
+ });
+ throw e;
+ }
+ };
+}
+
+/**
+ * Global request middleware that captures errors from API route requests.
+ * Should be added as the first entry in the `requestMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.request') as (...args: any[]) => any,
+ },
+};
+
+/**
+ * Global function middleware that captures errors from server function invocations.
+ * Should be added as the first entry in the `functionMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (...args: any[]) => any,
+ },
+};
+
+// Mark as internal so the Vite auto-instrumentation plugin skips these middleware
+addNonEnumerableProperty(sentryGlobalRequestMiddleware, SENTRY_INTERNAL, true);
+addNonEnumerableProperty(sentryGlobalFunctionMiddleware, SENTRY_INTERNAL, true);

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

@@ -6,6 +6,7 @@ export * from '@sentry/node';
 export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
+export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
 
 /**
  * A passthrough error boundary for the server that doesn't depend on any react. Error boundaries don't catch SSR errors

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

@@ -5,6 +5,7 @@ import type { MiddlewareWrapperOptions, TanStackMiddlewareBase } from '../common
 import { getMiddlewareSpanOptions } from './utils';
 
 const SENTRY_WRAPPED = '__SENTRY_WRAPPED__';
+export const SENTRY_INTERNAL = '__SENTRY_INTERNAL__';
 
 /**
  * Creates a proxy for the next function that ends the current span and restores the parent span.
@@ -39,8 +40,11 @@ function wrapMiddlewareWithSentry<T extends TanStackMiddlewareBase>(
  middleware: T,
  options: MiddlewareWrapperOptions,
 ): T {
- if ((middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED]) {
- // already instrumented
+ if (
+ (middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED] ||
+ (middleware as TanStackMiddlewareBase & { [SENTRY_INTERNAL]?: boolean })[SENTRY_INTERNAL]
+ ) {
+ // already instrumented or internal Sentry middleware
  return middleware;
  }
 

packages/tanstackstart-react/test/server/globalMiddleware.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const captureExceptionSpy = vi.fn();
+
+vi.mock('@sentry/core', async importOriginal => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ captureException: (...args: unknown[]) => captureExceptionSpy(...args),
+ };
+});
+
+// Import after mocks are set up
+const { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } =
+ await import('../../src/server/globalMiddleware');
+
+describe('sentryGlobalRequestMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.request', handled: false },
+ });
+ });
+
+ it('does not capture error when next() succeeds', async () => {
+ const next = vi.fn().mockResolvedValue('success');
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+ const result = await serverFn({ next });
+
+ expect(result).toBe('success');
+ expect(captureExceptionSpy).not.toHaveBeenCalled();
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalRequestMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});
+
+describe('sentryGlobalFunctionMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalFunctionMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.server_function', handled: false },
+ });
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalFunctionMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});

CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(tanstackstart-react): Add global sentry exception middlewares ([#19330](https://github.com/getsentry/sentry-javascript/pull/19330))**
+
+ The `sentryGlobalRequestMiddleware` and `sentryGlobalFunctionMiddleware` global middlewares capture unhandled exceptions thrown in TanStack Start API routes and server functions. Add them as the first entries in the `requestMiddleware` and `functionMiddleware` arrays of `createStart()`:
+
+ ```ts
+ import { createStart } from '@tanstack/react-start/server';
+ import { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from '@sentry/tanstackstart-react/server';
+
+ export default createStart({
+ requestMiddleware: [sentryGlobalRequestMiddleware, myRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, myFunctionMiddleware],
+ });
+ ```
+
 ### Important Changes
 
 - fix(node-core): Reduce bundle size by removing apm-js-collab and requiring pino >= 9.10 ([#18631](https://github.com/getsentry/sentry-javascript/pull/18631))

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.error.ts

@@ -1,16 +1,10 @@
-import * as Sentry from '@sentry/tanstackstart-react';
 import { createFileRoute } from '@tanstack/react-router';
 
 export const Route = createFileRoute('/api/error')({
  server: {
  handlers: {
  GET: async () => {
- try {
- throw new Error('Sentry API Route Test Error');
- } catch (error) {
- Sentry.captureException(error);
- throw error;
- }
+ throw new Error('Sentry API Route Test Error');
  },
  },
  },

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.flush.ts

@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { flush } from '@sentry/tanstackstart-react';
+
+export const Route = createFileRoute('/api/flush')({
+ server: {
+ handlers: {
+ GET: async () => {
+ await flush();
+ return new Response('ok');
+ },
+ },
+ },
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/ssr-error.tsx

@@ -0,0 +1,8 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/ssr-error')({
+ loader: () => {
+ throw new Error('Sentry SSR Test Error');
+ },
+ component: () => <div>SSR Error Page</div>,
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/start.ts

@@ -1,10 +1,11 @@
+import { sentryGlobalFunctionMiddleware, sentryGlobalRequestMiddleware } from '@sentry/tanstackstart-react';
 import { createStart } from '@tanstack/react-start';
 // NOTE: These are NOT wrapped - auto-instrumentation via the Vite plugin will wrap them
-import { globalRequestMiddleware, globalFunctionMiddleware } from './middleware';
+import { globalFunctionMiddleware, globalRequestMiddleware } from './middleware';
 
 export const startInstance = createStart(() => {
  return {
- requestMiddleware: [globalRequestMiddleware],
- functionMiddleware: [globalFunctionMiddleware],
+ requestMiddleware: [sentryGlobalRequestMiddleware, globalRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, globalFunctionMiddleware],
  };
 });

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

@@ -1,5 +1,5 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Sends client-side error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
@@ -51,17 +51,18 @@ test('Sends server-side function error to Sentry with auto-instrumentation', asy
  type: 'Error',
  value: 'Sentry Server Function Test Error',
  mechanism: {
+ type: 'auto.middleware.tanstackstart.server_function',
  handled: false,
  },
  },
  ],
  },
  });
 
- expect(errorEvent.transaction).toBe('/');
+ expect(errorEvent.transaction).toEqual(expect.stringContaining('GET /_serverFn/'));
 });
 
-test('Sends API route error to Sentry if manually instrumented', async ({ page }) => {
+test('Sends API route error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
  return errorEvent?.exception?.values?.[0]?.value === 'Sentry API Route Test Error';
  });
@@ -81,7 +82,8 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
  type: 'Error',
  value: 'Sentry API Route Test Error',
  mechanism: {
- handled: true,
+ type: 'auto.middleware.tanstackstart.request',
+ handled: false,
  },
  },
  ],
@@ -90,3 +92,28 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
 
  expect(errorEvent.transaction).toBe('GET /api/error');
 });
+
+// the sentry global middleware does not capture errors from SSR loader errors since they are serialized before they reach the middleware layer
+// this test verifies that the error is in fact not sent to Sentry
+test('Does not send SSR loader error to Sentry', async ({ baseURL, page }) => {
+ let errorEventOccurred = false;
+
+ waitForError('tanstackstart-react', event => {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Sentry SSR Test Error') {
+ errorEventOccurred = true;
+ }
+ return event?.transaction === 'GET /ssr-error';
+ });
+
+ const transactionEventPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.transaction === 'GET /ssr-error';
+ });
+
+ await page.goto('/ssr-error');
+
+ await transactionEventPromise;
+
+ await (await fetch(`${baseURL}/api/flush`)).text();
+
+ expect(errorEventOccurred).toBe(false);
+});

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

@@ -14,3 +14,15 @@ export { init } from './sdk';
 export function wrapMiddlewaresWithSentry<T extends TanStackMiddlewareBase>(middlewares: Record<string, T>): T[] {
  return Object.values(middlewares);
 }
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };

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

@@ -1,5 +1,8 @@
 export type TanStackMiddlewareBase = {
- options?: { server?: (...args: unknown[]) => unknown };
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ '~types': any;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ options: { server?: (...args: any[]) => any };
 };
 
 export type MiddlewareWrapperOptions = {

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

@@ -37,3 +37,6 @@ export declare const statsigIntegration: typeof clientSdk.statsigIntegration;
 export declare const unleashIntegration: typeof clientSdk.unleashIntegration;
 
 export declare const wrapMiddlewaresWithSentry: typeof serverSdk.wrapMiddlewaresWithSentry;
+
+export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
+export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;

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

@@ -0,0 +1,46 @@
+import { addNonEnumerableProperty, captureException } from '@sentry/core';
+import type { TanStackMiddlewareBase } from '../common/types';
+import { SENTRY_INTERNAL } from './middleware';
+
+function createSentryMiddlewareHandler(mechanismType: string) {
+ return async function sentryMiddlewareHandler({ next }: { next: () => Promise<unknown> }): Promise<unknown> {
+ try {
+ return await next();
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: mechanismType, handled: false },
+ });
+ throw e;
+ }
+ };
+}
+
+/**
+ * Global request middleware that captures errors from API route requests.
+ * Should be added as the first entry in the `requestMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.request') as (...args: any[]) => any,
+ },
+};
+
+/**
+ * Global function middleware that captures errors from server function invocations.
+ * Should be added as the first entry in the `functionMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (...args: any[]) => any,
+ },
+};
+
+// Mark as internal so the Vite auto-instrumentation plugin skips these middleware
+addNonEnumerableProperty(sentryGlobalRequestMiddleware, SENTRY_INTERNAL, true);
+addNonEnumerableProperty(sentryGlobalFunctionMiddleware, SENTRY_INTERNAL, true);

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

@@ -6,6 +6,7 @@ export * from '@sentry/node';
 export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
+export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
 
 /**
  * A passthrough error boundary for the server that doesn't depend on any react. Error boundaries don't catch SSR errors

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

@@ -5,6 +5,7 @@ import type { MiddlewareWrapperOptions, TanStackMiddlewareBase } from '../common
 import { getMiddlewareSpanOptions } from './utils';
 
 const SENTRY_WRAPPED = '__SENTRY_WRAPPED__';
+export const SENTRY_INTERNAL = '__SENTRY_INTERNAL__';
 
 /**
  * Creates a proxy for the next function that ends the current span and restores the parent span.
@@ -39,8 +40,11 @@ function wrapMiddlewareWithSentry<T extends TanStackMiddlewareBase>(
  middleware: T,
  options: MiddlewareWrapperOptions,
 ): T {
- if ((middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED]) {
- // already instrumented
+ if (
+ (middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED] ||
+ (middleware as TanStackMiddlewareBase & { [SENTRY_INTERNAL]?: boolean })[SENTRY_INTERNAL]
+ ) {
+ // already instrumented or internal Sentry middleware
  return middleware;
  }
 

packages/tanstackstart-react/test/server/globalMiddleware.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const captureExceptionSpy = vi.fn();
+
+vi.mock('@sentry/core', async importOriginal => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ captureException: (...args: unknown[]) => captureExceptionSpy(...args),
+ };
+});
+
+// Import after mocks are set up
+const { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } =
+ await import('../../src/server/globalMiddleware');
+
+describe('sentryGlobalRequestMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.request', handled: false },
+ });
+ });
+
+ it('does not capture error when next() succeeds', async () => {
+ const next = vi.fn().mockResolvedValue('success');
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+ const result = await serverFn({ next });
+
+ expect(result).toBe('success');
+ expect(captureExceptionSpy).not.toHaveBeenCalled();
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalRequestMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});
+
+describe('sentryGlobalFunctionMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalFunctionMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.server_function', handled: false },
+ });
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalFunctionMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});

CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(tanstackstart-react): Add global sentry exception middlewares ([#19330](https://github.com/getsentry/sentry-javascript/pull/19330))**
+
+ The `sentryGlobalRequestMiddleware` and `sentryGlobalFunctionMiddleware` global middlewares capture unhandled exceptions thrown in TanStack Start API routes and server functions. Add them as the first entries in the `requestMiddleware` and `functionMiddleware` arrays of `createStart()`:
+
+ ```ts
+ import { createStart } from '@tanstack/react-start/server';
+ import { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from '@sentry/tanstackstart-react/server';
+
+ export default createStart({
+ requestMiddleware: [sentryGlobalRequestMiddleware, myRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, myFunctionMiddleware],
+ });
+ ```
+
 ### Important Changes
 
 - fix(node-core): Reduce bundle size by removing apm-js-collab and requiring pino >= 9.10 ([#18631](https://github.com/getsentry/sentry-javascript/pull/18631))

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.error.ts

@@ -1,16 +1,10 @@
-import * as Sentry from '@sentry/tanstackstart-react';
 import { createFileRoute } from '@tanstack/react-router';
 
 export const Route = createFileRoute('/api/error')({
  server: {
  handlers: {
  GET: async () => {
- try {
- throw new Error('Sentry API Route Test Error');
- } catch (error) {
- Sentry.captureException(error);
- throw error;
- }
+ throw new Error('Sentry API Route Test Error');
  },
  },
  },

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.flush.ts

@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { flush } from '@sentry/tanstackstart-react';
+
+export const Route = createFileRoute('/api/flush')({
+ server: {
+ handlers: {
+ GET: async () => {
+ await flush();
+ return new Response('ok');
+ },
+ },
+ },
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/ssr-error.tsx

@@ -0,0 +1,8 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/ssr-error')({
+ loader: () => {
+ throw new Error('Sentry SSR Test Error');
+ },
+ component: () => <div>SSR Error Page</div>,
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/start.ts

@@ -1,10 +1,11 @@
+import { sentryGlobalFunctionMiddleware, sentryGlobalRequestMiddleware } from '@sentry/tanstackstart-react';
 import { createStart } from '@tanstack/react-start';
 // NOTE: These are NOT wrapped - auto-instrumentation via the Vite plugin will wrap them
-import { globalRequestMiddleware, globalFunctionMiddleware } from './middleware';
+import { globalFunctionMiddleware, globalRequestMiddleware } from './middleware';
 
 export const startInstance = createStart(() => {
  return {
- requestMiddleware: [globalRequestMiddleware],
- functionMiddleware: [globalFunctionMiddleware],
+ requestMiddleware: [sentryGlobalRequestMiddleware, globalRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, globalFunctionMiddleware],
  };
 });

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

@@ -1,5 +1,5 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Sends client-side error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
@@ -51,17 +51,18 @@ test('Sends server-side function error to Sentry with auto-instrumentation', asy
  type: 'Error',
  value: 'Sentry Server Function Test Error',
  mechanism: {
+ type: 'auto.middleware.tanstackstart.server_function',
  handled: false,
  },
  },
  ],
  },
  });
 
- expect(errorEvent.transaction).toBe('/');
+ expect(errorEvent.transaction).toEqual(expect.stringContaining('GET /_serverFn/'));
 });
 
-test('Sends API route error to Sentry if manually instrumented', async ({ page }) => {
+test('Sends API route error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
  return errorEvent?.exception?.values?.[0]?.value === 'Sentry API Route Test Error';
  });
@@ -81,7 +82,8 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
  type: 'Error',
  value: 'Sentry API Route Test Error',
  mechanism: {
- handled: true,
+ type: 'auto.middleware.tanstackstart.request',
+ handled: false,
  },
  },
  ],
@@ -90,3 +92,28 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
 
  expect(errorEvent.transaction).toBe('GET /api/error');
 });
+
+// the sentry global middleware does not capture errors from SSR loader errors since they are serialized before they reach the middleware layer
+// this test verifies that the error is in fact not sent to Sentry
+test('Does not send SSR loader error to Sentry', async ({ baseURL, page }) => {
+ let errorEventOccurred = false;
+
+ waitForError('tanstackstart-react', event => {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Sentry SSR Test Error') {
+ errorEventOccurred = true;
+ }
+ return event?.transaction === 'GET /ssr-error';
+ });
+
+ const transactionEventPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.transaction === 'GET /ssr-error';
+ });
+
+ await page.goto('/ssr-error');
+
+ await transactionEventPromise;
+
+ await (await fetch(`${baseURL}/api/flush`)).text();
+
+ expect(errorEventOccurred).toBe(false);
+});

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

@@ -14,3 +14,15 @@ export { init } from './sdk';
 export function wrapMiddlewaresWithSentry<T extends TanStackMiddlewareBase>(middlewares: Record<string, T>): T[] {
  return Object.values(middlewares);
 }
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };

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

@@ -1,5 +1,8 @@
 export type TanStackMiddlewareBase = {
- options?: { server?: (...args: unknown[]) => unknown };
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ '~types': any;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ options: { server?: (...args: any[]) => any };
 };
 
 export type MiddlewareWrapperOptions = {

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

@@ -37,3 +37,6 @@ export declare const statsigIntegration: typeof clientSdk.statsigIntegration;
 export declare const unleashIntegration: typeof clientSdk.unleashIntegration;
 
 export declare const wrapMiddlewaresWithSentry: typeof serverSdk.wrapMiddlewaresWithSentry;
+
+export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
+export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;

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

@@ -0,0 +1,46 @@
+import { addNonEnumerableProperty, captureException } from '@sentry/core';
+import type { TanStackMiddlewareBase } from '../common/types';
+import { SENTRY_INTERNAL } from './middleware';
+
+function createSentryMiddlewareHandler(mechanismType: string) {
+ return async function sentryMiddlewareHandler({ next }: { next: () => Promise<unknown> }): Promise<unknown> {
+ try {
+ return await next();
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: mechanismType, handled: false },
+ });
+ throw e;
+ }
+ };
+}
+
+/**
+ * Global request middleware that captures errors from API route requests.
+ * Should be added as the first entry in the `requestMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.request') as (...args: any[]) => any,
+ },
+};
+
+/**
+ * Global function middleware that captures errors from server function invocations.
+ * Should be added as the first entry in the `functionMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (...args: any[]) => any,
+ },
+};
+
+// Mark as internal so the Vite auto-instrumentation plugin skips these middleware
+addNonEnumerableProperty(sentryGlobalRequestMiddleware, SENTRY_INTERNAL, true);
+addNonEnumerableProperty(sentryGlobalFunctionMiddleware, SENTRY_INTERNAL, true);

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

@@ -6,6 +6,7 @@ export * from '@sentry/node';
 export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
+export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
 
 /**
  * A passthrough error boundary for the server that doesn't depend on any react. Error boundaries don't catch SSR errors

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

@@ -5,6 +5,7 @@ import type { MiddlewareWrapperOptions, TanStackMiddlewareBase } from '../common
 import { getMiddlewareSpanOptions } from './utils';
 
 const SENTRY_WRAPPED = '__SENTRY_WRAPPED__';
+export const SENTRY_INTERNAL = '__SENTRY_INTERNAL__';
 
 /**
  * Creates a proxy for the next function that ends the current span and restores the parent span.
@@ -39,8 +40,11 @@ function wrapMiddlewareWithSentry<T extends TanStackMiddlewareBase>(
  middleware: T,
  options: MiddlewareWrapperOptions,
 ): T {
- if ((middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED]) {
- // already instrumented
+ if (
+ (middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED] ||
+ (middleware as TanStackMiddlewareBase & { [SENTRY_INTERNAL]?: boolean })[SENTRY_INTERNAL]
+ ) {
+ // already instrumented or internal Sentry middleware
  return middleware;
  }
 

packages/tanstackstart-react/test/server/globalMiddleware.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const captureExceptionSpy = vi.fn();
+
+vi.mock('@sentry/core', async importOriginal => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ captureException: (...args: unknown[]) => captureExceptionSpy(...args),
+ };
+});
+
+// Import after mocks are set up
+const { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } =
+ await import('../../src/server/globalMiddleware');
+
+describe('sentryGlobalRequestMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.request', handled: false },
+ });
+ });
+
+ it('does not capture error when next() succeeds', async () => {
+ const next = vi.fn().mockResolvedValue('success');
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+ const result = await serverFn({ next });
+
+ expect(result).toBe('success');
+ expect(captureExceptionSpy).not.toHaveBeenCalled();
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalRequestMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});
+
+describe('sentryGlobalFunctionMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalFunctionMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.server_function', handled: false },
+ });
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalFunctionMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});

CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(tanstackstart-react): Add global sentry exception middlewares ([#19330](https://github.com/getsentry/sentry-javascript/pull/19330))**
+
+ The `sentryGlobalRequestMiddleware` and `sentryGlobalFunctionMiddleware` global middlewares capture unhandled exceptions thrown in TanStack Start API routes and server functions. Add them as the first entries in the `requestMiddleware` and `functionMiddleware` arrays of `createStart()`:
+
+ ```ts
+ import { createStart } from '@tanstack/react-start/server';
+ import { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from '@sentry/tanstackstart-react/server';
+
+ export default createStart({
+ requestMiddleware: [sentryGlobalRequestMiddleware, myRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, myFunctionMiddleware],
+ });
+ ```
+
 ### Important Changes
 
 - fix(node-core): Reduce bundle size by removing apm-js-collab and requiring pino >= 9.10 ([#18631](https://github.com/getsentry/sentry-javascript/pull/18631))

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.error.ts

@@ -1,16 +1,10 @@
-import * as Sentry from '@sentry/tanstackstart-react';
 import { createFileRoute } from '@tanstack/react-router';
 
 export const Route = createFileRoute('/api/error')({
  server: {
  handlers: {
  GET: async () => {
- try {
- throw new Error('Sentry API Route Test Error');
- } catch (error) {
- Sentry.captureException(error);
- throw error;
- }
+ throw new Error('Sentry API Route Test Error');
  },
  },
  },

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.flush.ts

@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { flush } from '@sentry/tanstackstart-react';
+
+export const Route = createFileRoute('/api/flush')({
+ server: {
+ handlers: {
+ GET: async () => {
+ await flush();
+ return new Response('ok');
+ },
+ },
+ },
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/ssr-error.tsx

@@ -0,0 +1,8 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/ssr-error')({
+ loader: () => {
+ throw new Error('Sentry SSR Test Error');
+ },
+ component: () => <div>SSR Error Page</div>,
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/start.ts

@@ -1,10 +1,11 @@
+import { sentryGlobalFunctionMiddleware, sentryGlobalRequestMiddleware } from '@sentry/tanstackstart-react';
 import { createStart } from '@tanstack/react-start';
 // NOTE: These are NOT wrapped - auto-instrumentation via the Vite plugin will wrap them
-import { globalRequestMiddleware, globalFunctionMiddleware } from './middleware';
+import { globalFunctionMiddleware, globalRequestMiddleware } from './middleware';
 
 export const startInstance = createStart(() => {
  return {
- requestMiddleware: [globalRequestMiddleware],
- functionMiddleware: [globalFunctionMiddleware],
+ requestMiddleware: [sentryGlobalRequestMiddleware, globalRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, globalFunctionMiddleware],
  };
 });

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

@@ -1,5 +1,5 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Sends client-side error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
@@ -51,17 +51,18 @@ test('Sends server-side function error to Sentry with auto-instrumentation', asy
  type: 'Error',
  value: 'Sentry Server Function Test Error',
  mechanism: {
+ type: 'auto.middleware.tanstackstart.server_function',
  handled: false,
  },
  },
  ],
  },
  });
 
- expect(errorEvent.transaction).toBe('/');
+ expect(errorEvent.transaction).toEqual(expect.stringContaining('GET /_serverFn/'));
 });
 
-test('Sends API route error to Sentry if manually instrumented', async ({ page }) => {
+test('Sends API route error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
  return errorEvent?.exception?.values?.[0]?.value === 'Sentry API Route Test Error';
  });
@@ -81,7 +82,8 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
  type: 'Error',
  value: 'Sentry API Route Test Error',
  mechanism: {
- handled: true,
+ type: 'auto.middleware.tanstackstart.request',
+ handled: false,
  },
  },
  ],
@@ -90,3 +92,28 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
 
  expect(errorEvent.transaction).toBe('GET /api/error');
 });
+
+// the sentry global middleware does not capture errors from SSR loader errors since they are serialized before they reach the middleware layer
+// this test verifies that the error is in fact not sent to Sentry
+test('Does not send SSR loader error to Sentry', async ({ baseURL, page }) => {
+ let errorEventOccurred = false;
+
+ waitForError('tanstackstart-react', event => {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Sentry SSR Test Error') {
+ errorEventOccurred = true;
+ }
+ return event?.transaction === 'GET /ssr-error';
+ });
+
+ const transactionEventPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.transaction === 'GET /ssr-error';
+ });
+
+ await page.goto('/ssr-error');
+
+ await transactionEventPromise;
+
+ await (await fetch(`${baseURL}/api/flush`)).text();
+
+ expect(errorEventOccurred).toBe(false);
+});

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

@@ -14,3 +14,15 @@ export { init } from './sdk';
 export function wrapMiddlewaresWithSentry<T extends TanStackMiddlewareBase>(middlewares: Record<string, T>): T[] {
  return Object.values(middlewares);
 }
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };

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

@@ -1,5 +1,8 @@
 export type TanStackMiddlewareBase = {
- options?: { server?: (...args: unknown[]) => unknown };
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ '~types': any;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ options: { server?: (...args: any[]) => any };
 };
 
 export type MiddlewareWrapperOptions = {

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

@@ -37,3 +37,6 @@ export declare const statsigIntegration: typeof clientSdk.statsigIntegration;
 export declare const unleashIntegration: typeof clientSdk.unleashIntegration;
 
 export declare const wrapMiddlewaresWithSentry: typeof serverSdk.wrapMiddlewaresWithSentry;
+
+export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
+export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;

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

@@ -0,0 +1,46 @@
+import { addNonEnumerableProperty, captureException } from '@sentry/core';
+import type { TanStackMiddlewareBase } from '../common/types';
+import { SENTRY_INTERNAL } from './middleware';
+
+function createSentryMiddlewareHandler(mechanismType: string) {
+ return async function sentryMiddlewareHandler({ next }: { next: () => Promise<unknown> }): Promise<unknown> {
+ try {
+ return await next();
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: mechanismType, handled: false },
+ });
+ throw e;
+ }
+ };
+}
+
+/**
+ * Global request middleware that captures errors from API route requests.
+ * Should be added as the first entry in the `requestMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.request') as (...args: any[]) => any,
+ },
+};
+
+/**
+ * Global function middleware that captures errors from server function invocations.
+ * Should be added as the first entry in the `functionMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (...args: any[]) => any,
+ },
+};
+
+// Mark as internal so the Vite auto-instrumentation plugin skips these middleware
+addNonEnumerableProperty(sentryGlobalRequestMiddleware, SENTRY_INTERNAL, true);
+addNonEnumerableProperty(sentryGlobalFunctionMiddleware, SENTRY_INTERNAL, true);

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

@@ -6,6 +6,7 @@ export * from '@sentry/node';
 export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
+export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
 
 /**
  * A passthrough error boundary for the server that doesn't depend on any react. Error boundaries don't catch SSR errors

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

@@ -5,6 +5,7 @@ import type { MiddlewareWrapperOptions, TanStackMiddlewareBase } from '../common
 import { getMiddlewareSpanOptions } from './utils';
 
 const SENTRY_WRAPPED = '__SENTRY_WRAPPED__';
+export const SENTRY_INTERNAL = '__SENTRY_INTERNAL__';
 
 /**
  * Creates a proxy for the next function that ends the current span and restores the parent span.
@@ -39,8 +40,11 @@ function wrapMiddlewareWithSentry<T extends TanStackMiddlewareBase>(
  middleware: T,
  options: MiddlewareWrapperOptions,
 ): T {
- if ((middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED]) {
- // already instrumented
+ if (
+ (middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED] ||
+ (middleware as TanStackMiddlewareBase & { [SENTRY_INTERNAL]?: boolean })[SENTRY_INTERNAL]
+ ) {
+ // already instrumented or internal Sentry middleware
  return middleware;
  }
 

packages/tanstackstart-react/test/server/globalMiddleware.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const captureExceptionSpy = vi.fn();
+
+vi.mock('@sentry/core', async importOriginal => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ captureException: (...args: unknown[]) => captureExceptionSpy(...args),
+ };
+});
+
+// Import after mocks are set up
+const { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } =
+ await import('../../src/server/globalMiddleware');
+
+describe('sentryGlobalRequestMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.request', handled: false },
+ });
+ });
+
+ it('does not capture error when next() succeeds', async () => {
+ const next = vi.fn().mockResolvedValue('success');
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+ const result = await serverFn({ next });
+
+ expect(result).toBe('success');
+ expect(captureExceptionSpy).not.toHaveBeenCalled();
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalRequestMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});
+
+describe('sentryGlobalFunctionMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalFunctionMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.server_function', handled: false },
+ });
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalFunctionMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});

CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(tanstackstart-react): Add global sentry exception middlewares ([#19330](https://github.com/getsentry/sentry-javascript/pull/19330))**
+
+ The `sentryGlobalRequestMiddleware` and `sentryGlobalFunctionMiddleware` global middlewares capture unhandled exceptions thrown in TanStack Start API routes and server functions. Add them as the first entries in the `requestMiddleware` and `functionMiddleware` arrays of `createStart()`:
+
+ ```ts
+ import { createStart } from '@tanstack/react-start/server';
+ import { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from '@sentry/tanstackstart-react/server';
+
+ export default createStart({
+ requestMiddleware: [sentryGlobalRequestMiddleware, myRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, myFunctionMiddleware],
+ });
+ ```
+
 ### Important Changes
 
 - fix(node-core): Reduce bundle size by removing apm-js-collab and requiring pino >= 9.10 ([#18631](https://github.com/getsentry/sentry-javascript/pull/18631))

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.error.ts

@@ -1,16 +1,10 @@
-import * as Sentry from '@sentry/tanstackstart-react';
 import { createFileRoute } from '@tanstack/react-router';
 
 export const Route = createFileRoute('/api/error')({
  server: {
  handlers: {
  GET: async () => {
- try {
- throw new Error('Sentry API Route Test Error');
- } catch (error) {
- Sentry.captureException(error);
- throw error;
- }
+ throw new Error('Sentry API Route Test Error');
  },
  },
  },

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.flush.ts

@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { flush } from '@sentry/tanstackstart-react';
+
+export const Route = createFileRoute('/api/flush')({
+ server: {
+ handlers: {
+ GET: async () => {
+ await flush();
+ return new Response('ok');
+ },
+ },
+ },
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/ssr-error.tsx

@@ -0,0 +1,8 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/ssr-error')({
+ loader: () => {
+ throw new Error('Sentry SSR Test Error');
+ },
+ component: () => <div>SSR Error Page</div>,
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/start.ts

@@ -1,10 +1,11 @@
+import { sentryGlobalFunctionMiddleware, sentryGlobalRequestMiddleware } from '@sentry/tanstackstart-react';
 import { createStart } from '@tanstack/react-start';
 // NOTE: These are NOT wrapped - auto-instrumentation via the Vite plugin will wrap them
-import { globalRequestMiddleware, globalFunctionMiddleware } from './middleware';
+import { globalFunctionMiddleware, globalRequestMiddleware } from './middleware';
 
 export const startInstance = createStart(() => {
  return {
- requestMiddleware: [globalRequestMiddleware],
- functionMiddleware: [globalFunctionMiddleware],
+ requestMiddleware: [sentryGlobalRequestMiddleware, globalRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, globalFunctionMiddleware],
  };
 });

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

@@ -1,5 +1,5 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Sends client-side error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
@@ -51,17 +51,18 @@ test('Sends server-side function error to Sentry with auto-instrumentation', asy
  type: 'Error',
  value: 'Sentry Server Function Test Error',
  mechanism: {
+ type: 'auto.middleware.tanstackstart.server_function',
  handled: false,
  },
  },
  ],
  },
  });
 
- expect(errorEvent.transaction).toBe('/');
+ expect(errorEvent.transaction).toEqual(expect.stringContaining('GET /_serverFn/'));
 });
 
-test('Sends API route error to Sentry if manually instrumented', async ({ page }) => {
+test('Sends API route error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
  return errorEvent?.exception?.values?.[0]?.value === 'Sentry API Route Test Error';
  });
@@ -81,7 +82,8 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
  type: 'Error',
  value: 'Sentry API Route Test Error',
  mechanism: {
- handled: true,
+ type: 'auto.middleware.tanstackstart.request',
+ handled: false,
  },
  },
  ],
@@ -90,3 +92,28 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
 
  expect(errorEvent.transaction).toBe('GET /api/error');
 });
+
+// the sentry global middleware does not capture errors from SSR loader errors since they are serialized before they reach the middleware layer
+// this test verifies that the error is in fact not sent to Sentry
+test('Does not send SSR loader error to Sentry', async ({ baseURL, page }) => {
+ let errorEventOccurred = false;
+
+ waitForError('tanstackstart-react', event => {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Sentry SSR Test Error') {
+ errorEventOccurred = true;
+ }
+ return event?.transaction === 'GET /ssr-error';
+ });
+
+ const transactionEventPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.transaction === 'GET /ssr-error';
+ });
+
+ await page.goto('/ssr-error');
+
+ await transactionEventPromise;
+
+ await (await fetch(`${baseURL}/api/flush`)).text();
+
+ expect(errorEventOccurred).toBe(false);
+});

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

@@ -14,3 +14,15 @@ export { init } from './sdk';
 export function wrapMiddlewaresWithSentry<T extends TanStackMiddlewareBase>(middlewares: Record<string, T>): T[] {
  return Object.values(middlewares);
 }
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };

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

@@ -1,5 +1,8 @@
 export type TanStackMiddlewareBase = {
- options?: { server?: (...args: unknown[]) => unknown };
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ '~types': any;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ options: { server?: (...args: any[]) => any };
 };
 
 export type MiddlewareWrapperOptions = {

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

@@ -37,3 +37,6 @@ export declare const statsigIntegration: typeof clientSdk.statsigIntegration;
 export declare const unleashIntegration: typeof clientSdk.unleashIntegration;
 
 export declare const wrapMiddlewaresWithSentry: typeof serverSdk.wrapMiddlewaresWithSentry;
+
+export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
+export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;

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

@@ -0,0 +1,46 @@
+import { addNonEnumerableProperty, captureException } from '@sentry/core';
+import type { TanStackMiddlewareBase } from '../common/types';
+import { SENTRY_INTERNAL } from './middleware';
+
+function createSentryMiddlewareHandler(mechanismType: string) {
+ return async function sentryMiddlewareHandler({ next }: { next: () => Promise<unknown> }): Promise<unknown> {
+ try {
+ return await next();
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: mechanismType, handled: false },
+ });
+ throw e;
+ }
+ };
+}
+
+/**
+ * Global request middleware that captures errors from API route requests.
+ * Should be added as the first entry in the `requestMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.request') as (...args: any[]) => any,
+ },
+};
+
+/**
+ * Global function middleware that captures errors from server function invocations.
+ * Should be added as the first entry in the `functionMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (...args: any[]) => any,
+ },
+};
+
+// Mark as internal so the Vite auto-instrumentation plugin skips these middleware
+addNonEnumerableProperty(sentryGlobalRequestMiddleware, SENTRY_INTERNAL, true);
+addNonEnumerableProperty(sentryGlobalFunctionMiddleware, SENTRY_INTERNAL, true);

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

@@ -6,6 +6,7 @@ export * from '@sentry/node';
 export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
+export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
 
 /**
  * A passthrough error boundary for the server that doesn't depend on any react. Error boundaries don't catch SSR errors

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

@@ -5,6 +5,7 @@ import type { MiddlewareWrapperOptions, TanStackMiddlewareBase } from '../common
 import { getMiddlewareSpanOptions } from './utils';
 
 const SENTRY_WRAPPED = '__SENTRY_WRAPPED__';
+export const SENTRY_INTERNAL = '__SENTRY_INTERNAL__';
 
 /**
  * Creates a proxy for the next function that ends the current span and restores the parent span.
@@ -39,8 +40,11 @@ function wrapMiddlewareWithSentry<T extends TanStackMiddlewareBase>(
  middleware: T,
  options: MiddlewareWrapperOptions,
 ): T {
- if ((middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED]) {
- // already instrumented
+ if (
+ (middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED] ||
+ (middleware as TanStackMiddlewareBase & { [SENTRY_INTERNAL]?: boolean })[SENTRY_INTERNAL]
+ ) {
+ // already instrumented or internal Sentry middleware
  return middleware;
  }
 

packages/tanstackstart-react/test/server/globalMiddleware.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const captureExceptionSpy = vi.fn();
+
+vi.mock('@sentry/core', async importOriginal => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ captureException: (...args: unknown[]) => captureExceptionSpy(...args),
+ };
+});
+
+// Import after mocks are set up
+const { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } =
+ await import('../../src/server/globalMiddleware');
+
+describe('sentryGlobalRequestMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.request', handled: false },
+ });
+ });
+
+ it('does not capture error when next() succeeds', async () => {
+ const next = vi.fn().mockResolvedValue('success');
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+ const result = await serverFn({ next });
+
+ expect(result).toBe('success');
+ expect(captureExceptionSpy).not.toHaveBeenCalled();
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalRequestMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});
+
+describe('sentryGlobalFunctionMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalFunctionMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.server_function', handled: false },
+ });
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalFunctionMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});

CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(tanstackstart-react): Add global sentry exception middlewares ([#19330](https://github.com/getsentry/sentry-javascript/pull/19330))**
+
+ The `sentryGlobalRequestMiddleware` and `sentryGlobalFunctionMiddleware` global middlewares capture unhandled exceptions thrown in TanStack Start API routes and server functions. Add them as the first entries in the `requestMiddleware` and `functionMiddleware` arrays of `createStart()`:
+
+ ```ts
+ import { createStart } from '@tanstack/react-start/server';
+ import { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from '@sentry/tanstackstart-react/server';
+
+ export default createStart({
+ requestMiddleware: [sentryGlobalRequestMiddleware, myRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, myFunctionMiddleware],
+ });
+ ```
+
 ### Important Changes
 
 - fix(node-core): Reduce bundle size by removing apm-js-collab and requiring pino >= 9.10 ([#18631](https://github.com/getsentry/sentry-javascript/pull/18631))

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.error.ts

@@ -1,16 +1,10 @@
-import * as Sentry from '@sentry/tanstackstart-react';
 import { createFileRoute } from '@tanstack/react-router';
 
 export const Route = createFileRoute('/api/error')({
  server: {
  handlers: {
  GET: async () => {
- try {
- throw new Error('Sentry API Route Test Error');
- } catch (error) {
- Sentry.captureException(error);
- throw error;
- }
+ throw new Error('Sentry API Route Test Error');
  },
  },
  },

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.flush.ts

@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { flush } from '@sentry/tanstackstart-react';
+
+export const Route = createFileRoute('/api/flush')({
+ server: {
+ handlers: {
+ GET: async () => {
+ await flush();
+ return new Response('ok');
+ },
+ },
+ },
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/ssr-error.tsx

@@ -0,0 +1,8 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/ssr-error')({
+ loader: () => {
+ throw new Error('Sentry SSR Test Error');
+ },
+ component: () => <div>SSR Error Page</div>,
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/start.ts

@@ -1,10 +1,11 @@
+import { sentryGlobalFunctionMiddleware, sentryGlobalRequestMiddleware } from '@sentry/tanstackstart-react';
 import { createStart } from '@tanstack/react-start';
 // NOTE: These are NOT wrapped - auto-instrumentation via the Vite plugin will wrap them
-import { globalRequestMiddleware, globalFunctionMiddleware } from './middleware';
+import { globalFunctionMiddleware, globalRequestMiddleware } from './middleware';
 
 export const startInstance = createStart(() => {
  return {
- requestMiddleware: [globalRequestMiddleware],
- functionMiddleware: [globalFunctionMiddleware],
+ requestMiddleware: [sentryGlobalRequestMiddleware, globalRequestMiddleware],
+ functionMiddleware: [sentryGlobalFunctionMiddleware, globalFunctionMiddleware],
  };
 });

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

@@ -1,5 +1,5 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Sends client-side error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
@@ -51,17 +51,18 @@ test('Sends server-side function error to Sentry with auto-instrumentation', asy
  type: 'Error',
  value: 'Sentry Server Function Test Error',
  mechanism: {
+ type: 'auto.middleware.tanstackstart.server_function',
  handled: false,
  },
  },
  ],
  },
  });
 
- expect(errorEvent.transaction).toBe('/');
+ expect(errorEvent.transaction).toEqual(expect.stringContaining('GET /_serverFn/'));
 });
 
-test('Sends API route error to Sentry if manually instrumented', async ({ page }) => {
+test('Sends API route error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
  return errorEvent?.exception?.values?.[0]?.value === 'Sentry API Route Test Error';
  });
@@ -81,7 +82,8 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
  type: 'Error',
  value: 'Sentry API Route Test Error',
  mechanism: {
- handled: true,
+ type: 'auto.middleware.tanstackstart.request',
+ handled: false,
  },
  },
  ],
@@ -90,3 +92,28 @@ test('Sends API route error to Sentry if manually instrumented', async ({ page }
 
  expect(errorEvent.transaction).toBe('GET /api/error');
 });
+
+// the sentry global middleware does not capture errors from SSR loader errors since they are serialized before they reach the middleware layer
+// this test verifies that the error is in fact not sent to Sentry
+test('Does not send SSR loader error to Sentry', async ({ baseURL, page }) => {
+ let errorEventOccurred = false;
+
+ waitForError('tanstackstart-react', event => {
+ if (!event.type && event.exception?.values?.[0]?.value === 'Sentry SSR Test Error') {
+ errorEventOccurred = true;
+ }
+ return event?.transaction === 'GET /ssr-error';
+ });
+
+ const transactionEventPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.transaction === 'GET /ssr-error';
+ });
+
+ await page.goto('/ssr-error');
+
+ await transactionEventPromise;
+
+ await (await fetch(`${baseURL}/api/flush`)).text();
+
+ expect(errorEventOccurred).toBe(false);
+});

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

@@ -14,3 +14,15 @@ export { init } from './sdk';
 export function wrapMiddlewaresWithSentry<T extends TanStackMiddlewareBase>(middlewares: Record<string, T>): T[] {
  return Object.values(middlewares);
 }
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };

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

@@ -1,5 +1,8 @@
 export type TanStackMiddlewareBase = {
- options?: { server?: (...args: unknown[]) => unknown };
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ '~types': any;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ options: { server?: (...args: any[]) => any };
 };
 
 export type MiddlewareWrapperOptions = {

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

@@ -37,3 +37,6 @@ export declare const statsigIntegration: typeof clientSdk.statsigIntegration;
 export declare const unleashIntegration: typeof clientSdk.unleashIntegration;
 
 export declare const wrapMiddlewaresWithSentry: typeof serverSdk.wrapMiddlewaresWithSentry;
+
+export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
+export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;

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

@@ -0,0 +1,46 @@
+import { addNonEnumerableProperty, captureException } from '@sentry/core';
+import type { TanStackMiddlewareBase } from '../common/types';
+import { SENTRY_INTERNAL } from './middleware';
+
+function createSentryMiddlewareHandler(mechanismType: string) {
+ return async function sentryMiddlewareHandler({ next }: { next: () => Promise<unknown> }): Promise<unknown> {
+ try {
+ return await next();
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: mechanismType, handled: false },
+ });
+ throw e;
+ }
+ };
+}
+
+/**
+ * Global request middleware that captures errors from API route requests.
+ * Should be added as the first entry in the `requestMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.request') as (...args: any[]) => any,
+ },
+};
+
+/**
+ * Global function middleware that captures errors from server function invocations.
+ * Should be added as the first entry in the `functionMiddleware` array of `createStart()`.
+ */
+export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = {
+ '~types': undefined,
+
+ options: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (...args: any[]) => any,
+ },
+};
+
+// Mark as internal so the Vite auto-instrumentation plugin skips these middleware
+addNonEnumerableProperty(sentryGlobalRequestMiddleware, SENTRY_INTERNAL, true);
+addNonEnumerableProperty(sentryGlobalFunctionMiddleware, SENTRY_INTERNAL, true);

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

@@ -6,6 +6,7 @@ export * from '@sentry/node';
 export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
+export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
 
 /**
  * A passthrough error boundary for the server that doesn't depend on any react. Error boundaries don't catch SSR errors

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

@@ -5,6 +5,7 @@ import type { MiddlewareWrapperOptions, TanStackMiddlewareBase } from '../common
 import { getMiddlewareSpanOptions } from './utils';
 
 const SENTRY_WRAPPED = '__SENTRY_WRAPPED__';
+export const SENTRY_INTERNAL = '__SENTRY_INTERNAL__';
 
 /**
  * Creates a proxy for the next function that ends the current span and restores the parent span.
@@ -39,8 +40,11 @@ function wrapMiddlewareWithSentry<T extends TanStackMiddlewareBase>(
  middleware: T,
  options: MiddlewareWrapperOptions,
 ): T {
- if ((middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED]) {
- // already instrumented
+ if (
+ (middleware as TanStackMiddlewareBase & { [SENTRY_WRAPPED]?: boolean })[SENTRY_WRAPPED] ||
+ (middleware as TanStackMiddlewareBase & { [SENTRY_INTERNAL]?: boolean })[SENTRY_INTERNAL]
+ ) {
+ // already instrumented or internal Sentry middleware
  return middleware;
  }
 

packages/tanstackstart-react/test/server/globalMiddleware.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const captureExceptionSpy = vi.fn();
+
+vi.mock('@sentry/core', async importOriginal => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ captureException: (...args: unknown[]) => captureExceptionSpy(...args),
+ };
+});
+
+// Import after mocks are set up
+const { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } =
+ await import('../../src/server/globalMiddleware');
+
+describe('sentryGlobalRequestMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.request', handled: false },
+ });
+ });
+
+ it('does not capture error when next() succeeds', async () => {
+ const next = vi.fn().mockResolvedValue('success');
+
+ const serverFn = sentryGlobalRequestMiddleware.options.server!;
+ const result = await serverFn({ next });
+
+ expect(result).toBe('success');
+ expect(captureExceptionSpy).not.toHaveBeenCalled();
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalRequestMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});
+
+describe('sentryGlobalFunctionMiddleware', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('captures error with correct mechanism when next() throws', async () => {
+ const error = new Error('test error');
+ const next = vi.fn().mockRejectedValue(error);
+
+ const serverFn = sentryGlobalFunctionMiddleware.options.server!;
+
+ await expect(serverFn({ next })).rejects.toThrow('test error');
+
+ expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+ mechanism: { type: 'auto.middleware.tanstackstart.server_function', handled: false },
+ });
+ });
+
+ it('has __SENTRY_INTERNAL__ flag set', () => {
+ expect((sentryGlobalFunctionMiddleware as unknown as Record<string, unknown>)['__SENTRY_INTERNAL__']).toBe(true);
+ });
+});