Skip to content

feat(nextjs): Add a tunnel route handler that sends only the event payload to Sentry - #25456

Draft
s1gr1d wants to merge 1 commit into
developfrom
sig/nextjs-tunnel-route-handler
Draft

s1gr1d wants to merge 1 commit into
developfrom
sig/nextjs-tunnel-route-handler

Conversation

@s1gr1d

@s1gr1d s1gr1d commented Oct 16, 2026 •

Copy link
Copy Markdown
Member

Today, tunnelRoute rewrites tunnel requests to Sentry as a proxy. This PR adds an opt-in handler mode: if app/sentry-tunnel/route.ts (or src/app/sentry-tunnel/route.ts) exists, the SDK rewrites the tunnel route internally to it, and the handler sends only the event payload to Sentry. Without the file, nothing changes.

// app/sentry-tunnel/route.ts
export { POST } from '@sentry/nextjs/tunnel';
  • When the file exists, but there's no tunnelRoute option, a warning is shown.
  • The rewrite is in beforeFiles, so a public file or page at the tunnel path cannot shadow it.
  • Like TanStack Start, the handler accepts only the server SDK's DSN. We also export createSentryTunnelRoute({ allowedDsns }) which covers other DSNs.
  • Fixed: Tunnel request spans were sent with span streaming, in rewrite mode too. They are now dropped.

Tested with unit tests, two new nextjs-16-tunnel variants (Turbopack/Node.js, webpack/edge) that also check the forwarded headers.

Also tested with a manual Vercel deploy on Next.js 14-16.

Fixes JS-3927

@s1gr1d
s1gr1d force-pushed the sig/nextjs-tunnel-route-handler branch from fb12663 to de8fd3d Compare October 16, 2026 13:21
@s1gr1d s1gr1d changed the title feat(nextjs): Add tunnel route handler that forwards only the envelope feat(nextjs): Add a tunnel route handler that sends only the event payload to Sentry Oct 16, 2026
@linear-code

linear-code Bot commented Oct 16, 2026

Copy link
Copy Markdown

JS-3927

@github-actions

Copy link
Copy Markdown
Contributor

size-limit report 📦

Path Size % Change Change
@sentry/browser 29.88 kB - -
@sentry/browser - with treeshaking flags 28.02 kB - -
@sentry/browser - with treeshaking flags tracing without tracing 27.92 kB - -
@sentry/browser (incl. Tracing) 52.07 kB - -
@sentry/browser (incl. Tracing + Span Streaming) 52.07 kB - -
@sentry/browser (incl. Tracing, Profiling) 55.02 kB - -
@sentry/browser (incl. Tracing, Replay) 91.82 kB - -
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags 80.68 kB - -
@sentry/browser (incl. Tracing, Replay with Canvas) 96.55 kB - -
@sentry/browser (incl. Tracing, Replay, Feedback) 109.49 kB - -
@sentry/browser (incl. Feedback) 47.4 kB - -
@sentry/browser (incl. sendFeedback) 34.94 kB - -
@sentry/browser (incl. FeedbackAsync) 40.05 kB - -
@sentry/browser (incl. Metrics) 30.9 kB - -
@sentry/browser (incl. Logs) 31.18 kB - -
@sentry/browser (incl. Metrics & Logs) 31.81 kB - -
@sentry/react 31.7 kB - -
@sentry/react (incl. Tracing) 54.39 kB - -
@sentry/vue 38.04 kB - -
@sentry/vue (incl. Tracing) 55.01 kB - -
@sentry/svelte 29.9 kB - -
@sentry/remix (Remix 3 client bundle) 57.08 kB - -
CDN Bundle 31.64 kB - -
CDN Bundle (incl. Tracing) 52.58 kB - -
CDN Bundle (incl. Logs, Metrics) 33.84 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) 54.52 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) 74.77 kB - -
CDN Bundle (incl. Tracing, Replay) 90.25 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) 92.18 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) 96.4 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) 98.34 kB - -
CDN Bundle - uncompressed 93.18 kB - -
CDN Bundle (incl. Tracing) - uncompressed 156.03 kB - -
CDN Bundle (incl. Logs, Metrics) - uncompressed 99.72 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed 161.99 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed 229.76 kB - -
CDN Bundle (incl. Tracing, Replay) - uncompressed 276.2 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed 282.14 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed 289.9 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed 295.84 kB - -
@sentry/nextjs (client) 56.84 kB +0.07% +39 B 🔺
@sentry/sveltekit (client) 52.45 kB - -
@sentry/core/server 41.12 kB - -
@sentry/core/browser 13.81 kB - -
@sentry/node 152.85 kB +0.01% +10 B 🔺
@sentry/node/import (ESM hook with diagnostics-channel injection) 83.84 kB - -
@sentry/node - without tracing 94.64 kB +0.01% +4 B 🔺
@sentry/node - without channel injection 131.08 kB +0.01% +1 B 🔺
@sentry/aws-serverless 102.8 kB +0.01% +3 B 🔺
@sentry/cloudflare (withSentry) - minified 210.6 kB - -
@sentry/cloudflare (withSentry) 522.53 kB - -
@sentry/nextjs/cloudflare (withSentry) - minified 228.27 kB - -

View base workflow run

@s1gr1d

s1gr1d commented Oct 16, 2026

Copy link
Copy Markdown
Member Author

bugbot run

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit de8fd3d. Configure here.

await page.goto('/');
await pageloadSpanPromise;
// Wait for the server to send the spans that the tunnel request would wrongly produce
await page.waitForTimeout(3000);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tunnel test sleeps to assert absence

Low Severity

The new handler test asserts that tunnel requests create no server spans by sleeping for three seconds after pageload. Absence checks that wait on a timeout stay racy under load and can pass while a late span still arrives.

Fix in Cursor Fix in Web

Triggered by project rule: PR Review Guidelines for Cursor Bot

Reviewed by Cursor Bugbot for commit de8fd3d. Configure here.

const ingestSpans = allSpans.filter(
span =>
getSpanOp(span) === 'http.client' &&
!!getStringAttribute(span, 'url.full')?.startsWith('http://localhost:3031/'),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tunnel tests hardcode span attributes

Low Severity

New span assertions compare http.request.method and url.full (and http.target / next.route in the unit tests) as raw strings. Those names already have constants in @sentry/conventions.

Additional Locations (1)
Fix in Cursor Fix in Web

Triggered by project rule: PR Review Guidelines for Cursor Bot

Reviewed by Cursor Bugbot for commit de8fd3d. Configure here.

@logaretm logaretm left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tiny issue and a small FYI, LGTM and looks nice!

}

// Like the SDK transports, so that the forward creates no spans, breadcrumbs or trace headers.
return suppressTracing(() => handleTunnelRequest({ request, allowedDsns }));

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI: This will lose the actual client IP, so relay will think the server is the user. Another issue is it parses the whole payload only to re-serialize it again.

This is pr-existing in the current tunnel utils, I'm handling both concern in my project stack atm so let's keep it. Just an FYI.

Check #25199 for reference.

projectDir: string = process.cwd(),
): string | undefined {
// Like Next.js, ignore `src/app` if there is a root `app` directory.
const appDir = ['app', 'src/app'].find(dir => getStats(path.join(projectDir, dir))?.isDirectory());

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the root has pages/ and the handler is in src/app/sentry-tunnel/route.ts, this picks src/app and enables handler mode.

Next.js ignores src/ when app or pages exists in the root, so /sentry-tunnel 404s and all events are lost. Checking for a root pages too fixes it:

Suggested change
const appDir = ['app', 'src/app'].find(dir => getStats(path.join(projectDir, dir))?.isDirectory());
const hasRootDir = ['app', 'pages'].some(dir => getStats(path.join(projectDir, dir))?.isDirectory());
const appDir = hasRootDir ? 'app' : 'src/app';

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants