From a8806c15e56772589a1e4865c72951530e11f094 Mon Sep 17 00:00:00 2001 From: Lazar Nikolov Date: Tue, 28 Apr 2026 10:23:58 -0400 Subject: [PATCH 1/4] docs(tanstackstart-react): Document tunnel route adapter Surface the new tunnel APIs shipped in sentry-javascript#20264: `sentryTanstackStart({ tunnelRoute })` for the managed Vite-plugin path and `createSentryTunnelRoute` for users who need to define the route file themselves. - Replace the generic tunneling include in Step 5 of the setup guide with TanStack-specific copy that recommends `tunnelRoute: true`. - Add a `Tunnel Route` section to the `sentryTanstackStart` feature page covering all three accepted shapes (`true`, static string, object), plus override and opaque-path caveats. - Add a dedicated `createSentryTunnelRoute` feature page with a file route example, the matching client `tunnel` reminder, and `allowedDsns` fallback behavior. Version markers are placeholders and need to be filled in once the `@sentry/tanstackstart-react` release ships. Refs JS-2144 Co-Authored-By: Claude --- .../features/createSentryTunnelRoute.mdx | 58 +++++++++++++++++++ .../features/sentryTanstackStart.mdx | 58 +++++++++++++++++++ .../guides/tanstackstart-react/index.mdx | 23 +++++++- 3 files changed, 138 insertions(+), 1 deletion(-) create mode 100644 docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx diff --git a/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx b/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx new file mode 100644 index 0000000000000..fb11508037ef6 --- /dev/null +++ b/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx @@ -0,0 +1,58 @@ +--- +title: createSentryTunnelRoute +description: "Learn how to manually define a Sentry tunnel route in your TanStack Start app." +--- + + + + + If you can use the `sentryTanstackStart` Vite plugin, prefer its + [`tunnelRoute`](/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart/#tunnel-route) + option. It registers the route for you and automatically wires up the client + `tunnel` option. Use `createSentryTunnelRoute` only when you need full control over + the route file, the DSN allowlist, or can't use the Vite plugin. + + +The `createSentryTunnelRoute` helper returns a TanStack Start server-route configuration with a `POST` handler that forwards Sentry envelopes to Sentry's ingest servers. Use it inside a file route to expose a same-origin tunnel endpoint. + +## Usage + +Create a server route at the path you want to tunnel through, and pass the list of DSNs you want to allow: + +```ts {filename:src/routes/monitor.ts} +import { createFileRoute } from "@tanstack/react-router"; +import * as Sentry from "@sentry/tanstackstart-react"; + +export const Route = createFileRoute("/monitor")({ + server: Sentry.createSentryTunnelRoute({ + allowedDsns: ["___PUBLIC_DSN___"], + }), +}); +``` + +Then, set the matching `tunnel` option in your client `Sentry.init()` so the browser SDK sends events to your route instead of directly to Sentry: + +```ts {filename:src/router.tsx} {5} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // ... + tunnel: "/monitor", +}); +``` + +## Options + +### `allowedDsns` + +A list of DSN strings that the route is allowed to forward to. The route validates each incoming envelope against this list and rejects any DSN that isn't allowed. + +If `allowedDsns` is omitted or empty, the route falls back to the DSN of the active server-side Sentry SDK at runtime. If neither is available, requests to the route return a 500 response. + +```ts {filename:src/routes/monitor.ts} +Sentry.createSentryTunnelRoute({ + allowedDsns: [ + "https://public@o0.ingest.sentry.io/1", + "https://public@o0.ingest.sentry.io/2", + ], +}); +``` diff --git a/docs/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart.mdx b/docs/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart.mdx index 2d4d08d5d7662..2f9c938641d84 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart.mdx @@ -61,3 +61,61 @@ sentryTanstackStart({ autoInstrumentMiddleware: false, }), ``` + +## Tunnel Route + + + +The `tunnelRoute` option registers a same-origin TanStack Start server route that forwards Sentry envelopes to Sentry's ingest servers. It also automatically sets the client `tunnel` option in `Sentry.init()` so browser events go through that route. This helps avoid ad blockers and corporate firewalls that block requests to `*.sentry.io`. + +`tunnelRoute` accepts three shapes: + +### `tunnelRoute: true` (recommended) + +Generates an opaque, unguessable route path for each dev session and production build. Because the path changes between builds, ad blockers can't reliably target it. + +```typescript {filename:vite.config.ts} +sentryTanstackStart({ + tunnelRoute: true, +}), +``` + +### Static path + +Pass a string to use a fixed route path. This is easier to reason about, but a known path is easier for ad blockers to add to a list. + +```typescript {filename:vite.config.ts} +sentryTanstackStart({ + tunnelRoute: "/monitor", +}), +``` + +### Object form + +Use the object form to control the DSN allowlist or set a static path explicitly: + +```typescript {filename:vite.config.ts} +sentryTanstackStart({ + tunnelRoute: { + allowedDsns: ["___PUBLIC_DSN___"], + path: "/monitor", + }, +}), +``` + +- **`allowedDsns`** — only envelopes targeting one of these DSNs are forwarded. If omitted or empty, the route falls back to the DSN of the active server-side Sentry SDK at runtime. +- **`path`** — the public route path. If omitted, an opaque path is generated (same behavior as `tunnelRoute: true`). + + + If you also pass `tunnel` to `Sentry.init()`, the runtime option wins and the + managed tunnel route is bypassed. The SDK logs a warning when this happens. + + + + When using `tunnelRoute: true` (or the object form without `path`), the + generated path changes for each dev session and each production build. Don't + hard-code it elsewhere in your app or infrastructure. + diff --git a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx index 1ce1a5de966b3..a5dec4c6e09d0 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx @@ -347,7 +347,28 @@ If you need more control over the upload process, see our [source maps guide](/p ## Step 5: Avoid Ad Blockers With Tunneling (Optional) - +Ad blockers and corporate firewalls often block requests to `*.sentry.io`, which can cause events to be dropped before they reach Sentry. To work around this, you can tunnel events through a same-origin route in your TanStack Start app. + +The `sentryTanstackStart` Vite plugin can register a tunnel route for you and automatically wire up the client `tunnel` option: + +```typescript {filename:vite.config.ts} {9} +import { defineConfig } from "vite"; +import { tanstackStart } from "@tanstack/react-start/plugin/vite"; +import { sentryTanstackStart } from "@sentry/tanstackstart-react/vite"; + +export default defineConfig({ + plugins: [ + tanstackStart(), + sentryTanstackStart({ + tunnelRoute: true, + }), + ], +}); +``` + +With `tunnelRoute: true`, an opaque route path is generated for each dev session and production build, making it harder for ad blockers to target. See the [`sentryTanstackStart`](/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart/#tunnel-route) feature page for static paths and the full set of options. + +If you can't use the Vite plugin, or you need full control over the route file and DSN allowlist, use [`createSentryTunnelRoute`](/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute/) to define the route yourself. ## Step 6: Verify From a8285632e8e05d676005419d9b1977c7331a1f50 Mon Sep 17 00:00:00 2001 From: Lazar Nikolov Date: Wed, 29 Apr 2026 16:01:47 -0400 Subject: [PATCH 2/4] chore(tanstackstart-react): Set AvailableSince version to 10.51.0 The tunnel route adapter shipped in @sentry/tanstackstart-react@10.51.0. Replace both TBD placeholders with the actual version. Co-Authored-By: Claude Opus 4.6 --- .../tanstackstart-react/features/createSentryTunnelRoute.mdx | 2 +- .../guides/tanstackstart-react/features/sentryTanstackStart.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx b/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx index fb11508037ef6..dbbd8e52dc7e4 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx @@ -3,7 +3,7 @@ title: createSentryTunnelRoute description: "Learn how to manually define a Sentry tunnel route in your TanStack Start app." --- - + If you can use the `sentryTanstackStart` Vite plugin, prefer its diff --git a/docs/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart.mdx b/docs/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart.mdx index 2f9c938641d84..8e971320d2e54 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart.mdx @@ -64,7 +64,7 @@ sentryTanstackStart({ ## Tunnel Route - + The `tunnelRoute` option registers a same-origin TanStack Start server route that forwards Sentry envelopes to Sentry's ingest servers. It also automatically sets the client `tunnel` option in `Sentry.init()` so browser events go through that route. This helps avoid ad blockers and corporate firewalls that block requests to `*.sentry.io`. From 027e60d3b0d2031d45f9ee32b77d6fa4f6b0134a Mon Sep 17 00:00:00 2001 From: Lazar Nikolov Date: Wed, 29 Apr 2026 16:15:51 -0400 Subject: [PATCH 3/4] fix(tanstackstart-react): Use consistent code fence language markers Co-Authored-By: Claude Opus 4.6 --- .../features/createSentryTunnelRoute.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx b/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx index dbbd8e52dc7e4..6ae4d5a632e4e 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx @@ -19,7 +19,7 @@ The `createSentryTunnelRoute` helper returns a TanStack Start server-route confi Create a server route at the path you want to tunnel through, and pass the list of DSNs you want to allow: -```ts {filename:src/routes/monitor.ts} +```typescript {filename:src/routes/monitor.ts} import { createFileRoute } from "@tanstack/react-router"; import * as Sentry from "@sentry/tanstackstart-react"; @@ -32,7 +32,7 @@ export const Route = createFileRoute("/monitor")({ Then, set the matching `tunnel` option in your client `Sentry.init()` so the browser SDK sends events to your route instead of directly to Sentry: -```ts {filename:src/router.tsx} {5} +```tsx {filename:src/router.tsx} {5} Sentry.init({ dsn: "___PUBLIC_DSN___", // ... @@ -48,7 +48,7 @@ A list of DSN strings that the route is allowed to forward to. The route validat If `allowedDsns` is omitted or empty, the route falls back to the DSN of the active server-side Sentry SDK at runtime. If neither is available, requests to the route return a 500 response. -```ts {filename:src/routes/monitor.ts} +```typescript {filename:src/routes/monitor.ts} Sentry.createSentryTunnelRoute({ allowedDsns: [ "https://public@o0.ingest.sentry.io/1", From 0815ed2f2e17c49f6a34122748ee24b4c28ced48 Mon Sep 17 00:00:00 2001 From: Lazar Nikolov Date: Wed, 29 Apr 2026 16:21:32 -0400 Subject: [PATCH 4/4] fix(tanstackstart-react): Correct line highlight for tunnel option Co-Authored-By: Claude Opus 4.6 --- .../tanstackstart-react/features/createSentryTunnelRoute.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx b/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx index 6ae4d5a632e4e..0242e493afbca 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx @@ -32,7 +32,7 @@ export const Route = createFileRoute("/monitor")({ Then, set the matching `tunnel` option in your client `Sentry.init()` so the browser SDK sends events to your route instead of directly to Sentry: -```tsx {filename:src/router.tsx} {5} +```tsx {filename:src/router.tsx} {4} Sentry.init({ dsn: "___PUBLIC_DSN___", // ...