Skip to content

Commit 796bf82

Browse files
nikolovlazarclaude
nikolovlazar
and
claude
authored
docs(tanstackstart-react): Document tunnel route adapter (#17504)
## DESCRIBE YOUR PR Documents the new tunnel APIs shipped in [sentry-javascript#20264](getsentry/sentry-javascript#20264) for `@sentry/tanstackstart-react@10.51.0`. The SDK now exposes two ways to tunnel browser events through a same-origin route to dodge ad blockers and corporate firewalls: - **`sentryTanstackStart({ tunnelRoute })`** — Vite plugin option that auto-registers the route AND auto-sets the client `tunnel` option. Recommended path. - **`createSentryTunnelRoute({ allowedDsns? })`** — manual server-route helper for users who need full control over the route file or DSN allowlist, or can't use the Vite plugin. Changes: - Replace the generic tunneling include in Step 5 of the TanStack Start setup guide with TanStack-specific copy that recommends `tunnelRoute: true` (opaque path regenerated each build) and links to both feature pages. - Add a `Tunnel Route` section to the existing `sentryTanstackStart` feature page covering all three accepted shapes (`true`, static string, `{ allowedDsns, path }`), plus override behavior and the opaque-path caveat. - Add a new dedicated `createSentryTunnelRoute` feature page (auto-discovered via `<PageGrid />`) with a `src/routes/monitor.ts` example, the matching client `tunnel` reminder, and `allowedDsns` fallback behavior. Refs JS-2144 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [x] `<AvailableSince>` versions set to `10.51.0` - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent dea5aa4 commit 796bf82

3 files changed

Lines changed: 138 additions & 1 deletion

File tree

‎docs/platforms/javascript/guides/tanstackstart-react/features/createSentryTunnelRoute.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: createSentryTunnelRoute
3+
description: "Learn how to manually define a Sentry tunnel route in your TanStack Start app."
4+
---
5+
6+
<AvailableSince version="10.51.0" />
7+
8+
<Alert level="info">
9+
If you can use the `sentryTanstackStart` Vite plugin, prefer its
10+
[`tunnelRoute`](/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart/#tunnel-route)
11+
option. It registers the route for you and automatically wires up the client
12+
`tunnel` option. Use `createSentryTunnelRoute` only when you need full control over
13+
the route file, the DSN allowlist, or can't use the Vite plugin.
14+
</Alert>
15+
16+
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.
17+
18+
## Usage
19+
20+
Create a server route at the path you want to tunnel through, and pass the list of DSNs you want to allow:
21+
22+
```typescript {filename:src/routes/monitor.ts}
23+
import { createFileRoute } from "@tanstack/react-router";
24+
import * as Sentry from "@sentry/tanstackstart-react";
25+
26+
export const Route = createFileRoute("/monitor")({
27+
server: Sentry.createSentryTunnelRoute({
28+
allowedDsns: ["___PUBLIC_DSN___"],
29+
}),
30+
});
31+
```
32+
33+
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:
34+
35+
```tsx {filename:src/router.tsx} {4}
36+
Sentry.init({
37+
dsn: "___PUBLIC_DSN___",
38+
// ...
39+
tunnel: "/monitor",
40+
});
41+
```
42+
43+
## Options
44+
45+
### `allowedDsns`
46+
47+
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.
48+
49+
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.
50+
51+
```typescript {filename:src/routes/monitor.ts}
52+
Sentry.createSentryTunnelRoute({
53+
allowedDsns: [
54+
"https://public@o0.ingest.sentry.io/1",
55+
"https://public@o0.ingest.sentry.io/2",
56+
],
57+
});
58+
```

‎docs/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,3 +61,61 @@ sentryTanstackStart({
6161
autoInstrumentMiddleware: false,
6262
}),
6363
```
64+
65+
## Tunnel Route
66+
67+
<AvailableSince version="10.51.0" />
68+
69+
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`.
70+
71+
`tunnelRoute` accepts three shapes:
72+
73+
### `tunnelRoute: true` (recommended)
74+
75+
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.
76+
77+
```typescript {filename:vite.config.ts}
78+
sentryTanstackStart({
79+
tunnelRoute: true,
80+
}),
81+
```
82+
83+
### Static path
84+
85+
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.
86+
87+
```typescript {filename:vite.config.ts}
88+
sentryTanstackStart({
89+
tunnelRoute: "/monitor",
90+
}),
91+
```
92+
93+
### Object form
94+
95+
Use the object form to control the DSN allowlist or set a static path explicitly:
96+
97+
```typescript {filename:vite.config.ts}
98+
sentryTanstackStart({
99+
tunnelRoute: {
100+
allowedDsns: ["___PUBLIC_DSN___"],
101+
path: "/monitor",
102+
},
103+
}),
104+
```
105+
106+
- **`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.
107+
- **`path`** — the public route path. If omitted, an opaque path is generated (same behavior as `tunnelRoute: true`).
108+
109+
<Alert
110+
level="info"
111+
title="Setting `tunnel` in `Sentry.init()` overrides this option"
112+
>
113+
If you also pass `tunnel` to `Sentry.init()`, the runtime option wins and the
114+
managed tunnel route is bypassed. The SDK logs a warning when this happens.
115+
</Alert>
116+
117+
<Alert level="warning" title="Opaque paths are not stable">
118+
When using `tunnelRoute: true` (or the object form without `path`), the
119+
generated path changes for each dev session and each production build. Don't
120+
hard-code it elsewhere in your app or infrastructure.
121+
</Alert>

‎docs/platforms/javascript/guides/tanstackstart-react/index.mdx‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -347,7 +347,28 @@ If you need more control over the upload process, see our [source maps guide](/p
347347

348348
## Step 5: Avoid Ad Blockers With Tunneling (Optional)
349349

350-
<PlatformContent includePath="getting-started-tunneling" />
350+
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.
351+
352+
The `sentryTanstackStart` Vite plugin can register a tunnel route for you and automatically wire up the client `tunnel` option:
353+
354+
```typescript {filename:vite.config.ts} {9}
355+
import { defineConfig } from "vite";
356+
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
357+
import { sentryTanstackStart } from "@sentry/tanstackstart-react/vite";
358+
359+
export default defineConfig({
360+
plugins: [
361+
tanstackStart(),
362+
sentryTanstackStart({
363+
tunnelRoute: true,
364+
}),
365+
],
366+
});
367+
```
368+
369+
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.
370+
371+
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.
351372

352373
## Step 6: Verify
353374

0 commit comments

Comments
 (0)