diff --git a/docs/platforms/javascript/common/configuration/tree-shaking.mdx b/docs/platforms/javascript/common/configuration/tree-shaking.mdx index aae211e95447f..0f207a2a8bc34 100644 --- a/docs/platforms/javascript/common/configuration/tree-shaking.mdx +++ b/docs/platforms/javascript/common/configuration/tree-shaking.mdx @@ -75,35 +75,6 @@ For more details, see the documentation for the specific bundler plugin you're u - - -### Tree Shaking With Next.js - -To tree shake Sentry debug code in Next.js projects, use webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/) in your Next.js configuration like in the example below: - -```javascript {filename:next.config.(js|mjs)} -const nextConfig = { - webpack: (config, { webpack }) => { - config.plugins.push( - new webpack.DefinePlugin({ - __SENTRY_DEBUG__: false, - __SENTRY_TRACING__: false, - __RRWEB_EXCLUDE_IFRAME__: true, - __RRWEB_EXCLUDE_SHADOW_DOM__: true, - __SENTRY_EXCLUDE_REPLAY_WORKER__: true, - }) - ); - - // return the modified config - return config; - }, -}; -``` - -For more information on custom webpack configurations in Next.js, see [Custom Webpack Config](https://nextjs.org/docs/api-reference/next.config.js/custom-webpack-config) in the Next.js docs. - - - ### Manual Tree Shaking If you want to tree shake optional code, remove the code from your build output by replacing various flags in the Sentry SDK. Note that if you already configured tree shaking via the Sentry Bundler Plugins, you do not need to do this manually - the plugins will take care of it for you. @@ -120,9 +91,9 @@ Replacing this flag with `false` will tree shake any SDK code that's related to `__SENTRY_TRACING__` must not be replaced with `false` when you're using any - tracing-related SDK features (for example,`Sentry.startSpan()`). This - flag is intended to be used in combination with packages like `@sentry/next` - or `@sentry/sveltekit`, which automatically include the tracing functionality. + tracing-related SDK features (for example,`Sentry.startSpan()`). This flag is + intended to be used in combination with packages like `@sentry/next` or + `@sentry/sveltekit`, which automatically include the tracing functionality. diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index ee94a816e83c2..ca6e3e038bc48 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -314,3 +314,9 @@ Enables React component name tracking. When enabled, it annotates React componen A list of React component names to exclude from component annotation. + + + +Configuration options for tree shaking. Refer to the [tree shaking documentation](/platforms/javascript/guides/nextjs/configuration/tree-shaking) for more details. + + diff --git a/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx b/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx new file mode 100644 index 0000000000000..0efb9cd5e435e --- /dev/null +++ b/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx @@ -0,0 +1,94 @@ +--- +title: Tree Shaking +sidebar_order: 70 +description: "Learn how to reduce Sentry bundle size by tree shaking unused code." +keywords: ["bundle size", "webpack", "Next.js", "debug"] +--- + +The Sentry Next.js SDK supports [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) for Webpack builds with some additional configurations. + +If you want to minimize the bundle size of the Sentry SDK, we recommend reading through this page and applying the tree shaking configurations as shown. + + + +This guide is only relevant if you're using Webpack to build your Next.js application. Tree-shaking options are not supported for Turbopack builds at the moment. + + + +## Tree Shaking Optional Code + +The Sentry SDK ships with code that is not strictly required for it to collect your errors. This includes code to debug your Sentry configuration or code to enable tracing, for example. While debug code can be very useful in development environments, it's not typically necessary to include it in your production bundles where it takes up valuable space. The JavaScript SDK includes special flags in its CommonJS and ESM distributions, which can be used to facilitate tree shaking (removal) of this kind of code during the build process. + + + Anything that you don't import and use will automatically be tree + shaken away by Webpack. This means that optional integrations like Replay, + BrowserTracing, BrowserProfiling, and any unused utility methods won't be + included in your bundle unless you import and use them yourself. The rest of + this page relates to ways to tree shake internal SDK code, which isn't + strictly required unless you use certain features. + + +## Tree Shaking Options + +To tree shake Sentry debug code in Next.js projects, use `webpack.treeshake` options in your Next.js Sentry build configuration like in the example below: + +```javascript {filename:next.config.(js|mjs)} +const nextConfig = { + // your next.js config +}; + +withSentryConfig(nextConfig, { + webpack: { + treeshake: { + // Tree shaking options... + removeDebugLogging: false, + removeTracing: false, + excludeReplayIframe: false, + excludeReplayShadowDOM: false, + excludeReplayCompressionWorker: false, + }, + }, +}); +``` + +For more information on custom webpack configurations in Next.js, see [Custom Webpack Config](https://nextjs.org/docs/api-reference/next.config.js/custom-webpack-config) in the Next.js docs. + +The following sections will cover each available tree shaking option and how to configure them. + + + +Setting this option to `true` will remove all debug logging code from the Sentry SDK. Note that it has nothing to do with `enableLogs` or Sentry's logs product. + +These logs can be useful to help debug your Sentry configuration or issues with the Sentry SDK. + + + + + +Setting this option to `true` will remove all code related to tracing and performance monitoring. + +Note that you should not use any tracing-related SDK features (for example, `Sentry.startSpan()`) when this option is enabled, also this option has no effect if you did not add `browserTracingIntegration`. + + + + + +Setting this option to `true` will tree shake any SDK code related to capturing iframe content with [Session Replay](/platforms/javascript/session-replay/). It's only relevant when using Session Replay. Enable this option if you don't want to record any iframes. This has no effect if you did not add `replayIntegration`. + + + + + +Setting this option to `true` will tree shake any SDK code related to capturing shadow dom elements with [Session Replay](/platforms/javascript/session-replay/). It's only relevant when using Session Replay. Enable this flag if you don't want to record any shadow dom elements. This has no effect if you didn't add `replayIntegration`. + + + + + +Setting this option to `true` will tree shake any SDK code that's related to the included compression web worker for [Session Replay](/platforms/javascript/session-replay/). It's only relevant when using Session Replay. Enable this flag if you want to host a compression worker yourself. See Using a [Custom Compression Worker](/platforms/javascript/session-replay/configuration/#using-a-custom-compression-worker) for details. This has no effect if you did not add `replayIntegration`. + +**We don't recommend enabling this flag unless you provide a custom worker URL**. + + + +If you want to learn more about the available tree shaking flags and how to set them manually with different bundlers, see the [tree shaking documentation](/platforms/javascript/common/configuration/tree-shaking/#tree-shaking-with-webpack) for the JavaScript SDK.