docs(nextjs): added tree-shaking webpack config guide

[logaretm]

What

A PR to go in tandem with getsentry/sentry-javascript#18359 once it gets merged and released.

It documents the new tree-shaking options now abstracted away into webpack.treeshake namespace. It has a few differences to the existing tree-shaking flags under the hood:

• All options are optimized to be set to true to take effect, unlike the flags where some had to be set to true and some had to be set to false.
• Now exposed as an SDK webpack.treeshake build options rather than needing the user to be aware of the webpack define plugin API.

Marking it as a draft to avoid merging it before the PR goes live.

[linear]

JS-1222 Add treeshaking option for webpack

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
sentry-docs	Ready	Preview, Comment	Dec 18, 2025 3:33pm

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
develop-docs	Ignored	Preview	Dec 18, 2025 3:33pm

[inventarSarah]

👍
Added some suggestions

[inventarSarah]

These two sentences are a bit confusing to me -- which logs does it concern?

[logaretm]

It's a bit tricky 😅, so ... we have those DEBUG logs that show up when the user has debug: true but they aren't removed from the bundle.

So this option is supposed to remove them from the bundle, but we have a logs product enabled by enableLogs on the SDK configuration (not build options), so this is basically trying to avoid that very confusion, that it doesn't affect the logs product and it only affect those DEBUG statements.

What do you think we could do here to explain that? this has been always a confusion point for many users.

[inventarSarah]

Something like this, maybe?

Setting this option to true will remove all Sentry SDK debug logging code (the console logs that appear when you set debug: true in your SDK configuration). This doesn't affect Sentry's Logs product (controlled by the enableLogs option) or your app's logging.

[logaretm]

Yea, I think the console mention here nails it. Thanks! Pushed it!

[inventarSarah]

💫nice!

[Copilot]

Pull request overview

This PR adds comprehensive documentation for the new tree-shaking webpack configuration options in the Next.js SDK. It moves away from the older webpack DefinePlugin approach to a more user-friendly webpack.treeshake configuration namespace abstracted through the withSentryConfig function.

Key changes:

• New dedicated tree-shaking documentation page for Next.js with detailed explanations of all available options
• Updated build configuration documentation to reference the new webpack.treeshake options
• Removed the outdated Next.js tree-shaking section from the common configuration docs

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx	New comprehensive guide documenting the webpack.treeshake configuration options with examples and detailed descriptions of each option
docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx	Added webpack.treeshake option reference linking to the new tree-shaking documentation
docs/platforms/javascript/common/configuration/tree-shaking.mdx	Removed outdated Next.js-specific tree-shaking section using DefinePlugin and fixed minor formatting issues

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The code example shows all tree-shaking options set to false, which is also the default value. This might be confusing for users trying to understand how to actually enable tree-shaking. Consider either showing the options set to true to demonstrate enabling tree-shaking, or adding a comment explaining that these are the defaults and users should set them to true to enable the respective tree-shaking optimizations.

Suggested change

	// Tree shaking options...
	removeDebugLogging: false,
	removeTracing: false,
	excludeReplayIframe: false,
	excludeReplayShadowDOM: false,
	excludeReplayCompressionWorker: false,
	// Enable tree shaking by setting these options to true (defaults are all false).
	removeDebugLogging: true,
	removeTracing: true,
	excludeReplayIframe: true,
	excludeReplayShadowDOM: true,
	excludeReplayCompressionWorker: true,