ref(react, browser): make @sentry/react tree-shakeable by default

[anonrig]

Stop star-exporting the full @sentry/browser surface from @sentry/react so unused optional features are not forced into client bundles.

Problem

Apps that both statically import from @sentry/react and dynamically load it (common for deferring tracing after hydration) can end up shipping the entire browser barrel on the critical path.

With Rolldown (Vite 8), destructuring a dynamic import namespace is treated as using every export:

void import('@sentry/react').then((sentry) => {
  const { addIntegration, tanstackRouterBrowserTracingIntegration } = sentry;
  // ...
});

Because @sentry/react did export * from '@sentry/browser', that pulled Session Replay (~265KB), Feedback, AI instrumenters, feature-flag integrations, and unused React Router/Redux integrations into the main client chunk even when the app never referenced them.

Measured on a production-like Rolldown graph (static init + idle dynamic import):

Pattern	Bundle (approx.)
Before (full barrel + destructure)	~1000KB
After (curated root + subpath for TanStack)	~430–475KB, no @sentry/replay / rrweb

Solution

1. @sentry/browser/core — slim entry for error monitoring, default integrations, and common tracing/filtering APIs (no Replay, Feedback, AI, feature flags, profiling, …).
2. @sentry/react root — curated re-exports from @sentry/browser/core only (no export * from the full browser package).
3. Subpaths for optional React features so they stay off the root export list:
   • @sentry/react/tanstackrouter
   • @sentry/react/redux
   • @sentry/react/reactrouter, reactrouterv3–v7, reactrouter.compat
   • @sentry/react/optional-browser-api (Replay, Feedback, AI, …)
4. @sentry/nextjs / @sentry/gatsby re-export optional-browser-api so import * as Sentry from '@sentry/nextjs' keeps the historical surface.

Migration

Optional / router APIs are no longer available from the @sentry/react root:

// Before
import { replayIntegration, tanstackRouterBrowserTracingIntegration } from '@sentry/react';

// After
import { replayIntegration } from '@sentry/browser'; // or @sentry/replay
import { tanstackRouterBrowserTracingIntegration } from '@sentry/react/tanstackrouter';

Recommended pattern for deferred tracing without reintroducing the fat namespace:

import { init, addIntegration } from '@sentry/react';
import { tanstackRouterBrowserTracingIntegration } from '@sentry/react/tanstackrouter';

init({ dsn: '...' });

requestIdleCallback(() => {
  addIntegration(tanstackRouterBrowserTracingIntegration(router));
});

Test plan

• packages/react export-surface unit test (exports.treeshake.test.ts)
• yarn build:dev:filter @sentry/react succeeds
• CI: browser/react/nextjs/gatsby unit tests
• Confirm size-limit / package publish layout for new subpath entries

---

Note

Medium Risk
Public API break for anyone importing optional/router symbols from @sentry/react root; framework re-exports limit impact for Next/Gatsby/Remix users but direct React apps need migration.

Overview
Makes @sentry/react tree-shakeable by default so dynamic import('@sentry/react') (especially with Rolldown/Vite 8 namespace destructuring) no longer drags Replay, Feedback, AI instrumenters, and router/Redux code into the main chunk.

The root entry stops export * from '@sentry/browser' and instead re-exports a curated surface from new @sentry/browser/core. Optional browser APIs move to @sentry/react/optional-browser-api; React Router, Redux, and TanStack helpers move to package subpaths (/tanstackrouter, /redux, /reactrouterv6, etc.) with separate Rollup entrypoints and package.json exports.

Framework SDKs (@sentry/nextjs, @sentry/gatsby, @sentry/remix, @sentry/tanstackstart-react) re-export optional-browser-api (and Redux/TanStack where needed) so import * as Sentry from '@sentry/…' keeps the old symbols for those packages.

Breaking for direct @sentry/react users: replayIntegration, router integrations, createReduxEnhancer, etc. must be imported from @sentry/browser, subpaths, or dedicated packages. CHANGELOG, README, e2e fixtures, and exports.treeshake.test.ts document and enforce the new surface.

^{Reviewed by Cursor Bugbot for commit fd30d7d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[anonrig]

Automated fix: addressed CI failure in Build (@sentry/remix / @sentry/tanstackstart-react types).

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

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

^{Reviewed by Cursor Bugbot for commit cf92bd3. Configure here.}

[anonrig]

Automated fix: updated E2E apps for subpath/optional-browser-api imports.

[Lms24]

Hey @anonrig thanks for opening this PR! I understand the issue at hand and can see why the barrel-export style causes an issue with Rolldown at the moment (more on that below).

If we assume that bundlers are not smart enough for tree shaking dynamic imports, then I agree that the current exports of the top level Sentry packages are far from ideal. However, we have to weigh the proposed changes against a major usability trade-off: The top-level export is convenient. Users don't need to look up which subpath export contains what. It's just there. Moreover, it ensures usage parity between our NPM package and CDN bundles, something that has always been important for our users. If we were to change this, we'd need to consider that it would be a breaking change, affecting the majority of our users.

Ease of use of our SDKs is a priority for us. Bundle size, too. The Sentry JS SDKs are therefore designed to fully leverage tree shaking. We even provide advanced tree shaking options for users who are really bundle-size conscious.

If you use the SDK as documented, without dynamic imports, every modern bundler (basically everything after Webpack 4 and esbuild) is able to tree-shake. We don't document dynamically importing the SDK because in all our testing so far, it had no noticeable advantage over a classic eager import. Especially for an integration like BrowserTracing (i.e. tanstackRouterBrowserTracingIntegration in your case), it's essential that it is initialized as early as possible in the app lifecycle. Otherwise, there's risk of losing data. While the dynamic import is of course possible, there will be trade-offs. For example, network requests going out before the tracing integration is fully initialized will not carry Sentry's tracing headers, meaning, distributed tracing won't work for these requests.

Since you're using Rolldown and it indeed currently can't tree-shake dynamic imports, @logaretm took a stab at fixing this bug directly in Rolldown: rolldown/rolldown#10213. Once this lands, there should be noticeably better tree shaking for dynamically imported modules.

Our own overhead tests show little to no advantage when comparing an eagerly imported SDK setup with tracing to dynamically importing tracing:

(Actually throttled slow 4g Network)

(Lighthouse-Lantern simulated slow 4g speeds)

For specific integrations we provide Sentry.lazyLoadIntegration, which will lazily load a CDN bundle that only contains integration-specific code. It's a safe alternative for things like user feedback, where timing isn't critical.

The PR proposes to limit the top-level export surface to a set of "core" APIs. While I fully understand why this is proposed, I think defining this "core" set so that everyone is happy is close to impossible and we'd have to draw an arbitrary line. More importantly, assuming bundlers cannot tree shake dynamically imported code, you'd still end up with a considerable amount of unused code in the core part.

We're not dismissing the idea of lazy-loading parts of the SDK. In fact, it's on our to-do list to pick up after the next major version of the SDK lands. However, as we've seen, it requires careful consideration. I'm therefore closing this PR, since it is not a direction we'll take and we can't merge a breaking change at this time. Again, thank you for opening the PR!