Skip to content

Commit e1c7023

Browse files
logaretmchargomeinventarSarahCopilot
authored
docs(nextjs): added tree-shaking webpack config guide (#15790)
# 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. --------- Co-authored-by: Charly Gomez <charly.gomez@sentry.io> Co-authored-by: Sarah Mischinger <sarah@codingwriter.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent f305dbc commit e1c7023

File tree

3 files changed

+105
-32
lines changed

3 files changed

+105
-32
lines changed

‎docs/platforms/javascript/common/configuration/tree-shaking.mdx‎

Lines changed: 3 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -75,35 +75,6 @@ For more details, see the documentation for the specific bundler plugin you're u
7575

7676
</PlatformSection>
7777

78-
<PlatformSection supported={["javascript.nextjs"]}>
79-
80-
### Tree Shaking With Next.js
81-
82-
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:
83-
84-
```javascript {filename:next.config.(js|mjs)}
85-
const nextConfig = {
86-
webpack: (config, { webpack }) => {
87-
config.plugins.push(
88-
new webpack.DefinePlugin({
89-
__SENTRY_DEBUG__: false,
90-
__SENTRY_TRACING__: false,
91-
__RRWEB_EXCLUDE_IFRAME__: true,
92-
__RRWEB_EXCLUDE_SHADOW_DOM__: true,
93-
__SENTRY_EXCLUDE_REPLAY_WORKER__: true,
94-
})
95-
);
96-
97-
// return the modified config
98-
return config;
99-
},
100-
};
101-
```
102-
103-
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.
104-
105-
</PlatformSection>
106-
10778
### Manual Tree Shaking
10879

10980
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
12091

12192
<Alert>
12293
`__SENTRY_TRACING__` must not be replaced with `false` when you're using any
123-
tracing-related SDK features (for example,`Sentry.startSpan()`). This
124-
flag is intended to be used in combination with packages like `@sentry/next`
125-
or `@sentry/sveltekit`, which automatically include the tracing functionality.
94+
tracing-related SDK features (for example, `Sentry.startSpan()`). This flag is
95+
intended to be used in combination with packages like `@sentry/next` or
96+
`@sentry/sveltekit`, which automatically include the tracing functionality.
12697
</Alert>
12798

12899
<PlatformCategorySection supported={["browser"]}>

‎docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -314,3 +314,9 @@ Enables React component name tracking. When enabled, it annotates React componen
314314
A list of React component names to exclude from component annotation.
315315

316316
</SdkOption>
317+
318+
<SdkOption name="webpack.treeshake" type="object">
319+
320+
Configuration options for tree shaking. Refer to the [tree shaking documentation](/platforms/javascript/guides/nextjs/configuration/tree-shaking) for more details.
321+
322+
</SdkOption>

‎docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: Tree Shaking
3+
sidebar_order: 70
4+
description: "Learn how to reduce Sentry bundle size by tree shaking unused code."
5+
keywords: ["bundle size", "webpack", "Next.js", "debug"]
6+
---
7+
8+
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.
9+
10+
If you want to minimize the bundle size of the Sentry SDK, we recommend reading through this page and applying the tree-shaking configurations shown.
11+
12+
<Alert>
13+
14+
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.
15+
16+
</Alert>
17+
18+
## Tree-Shaking Optional Code
19+
20+
The Sentry Next.js SDK includes code that isn't strictly required for basic error collection, such as debug logging and tracing functionality. While debug code is useful during development, it adds unnecessary weight to your production bundles. The Next.js SDK provides tree shaking options through the `withSentryConfig` function, allowing you to remove this optional code during the webpack build process.
21+
22+
<Alert>
23+
Anything you don't import or use can be tree shaken by webpack. This means
24+
that optional integrations like Session Replay, Browser Tracing, Browser
25+
Profiling, and any unused utility methods won't be included in your bundle
26+
unless you import and use them. The rest of this page covers ways to tree
27+
shake internal SDK code, which you only need if you're using certain Sentry
28+
features.
29+
</Alert>
30+
31+
## Tree-Shaking Options
32+
33+
To tree shake Sentry debug code in Next.js projects, use `webpack.treeshake` options in your build configuration, like in this example:
34+
35+
```javascript {filename:next.config.(js|mjs)}
36+
const nextConfig = {
37+
// your next.js config
38+
};
39+
40+
withSentryConfig(nextConfig, {
41+
webpack: {
42+
treeshake: {
43+
// Tree shaking options...
44+
removeDebugLogging: false,
45+
removeTracing: false,
46+
excludeReplayIframe: false,
47+
excludeReplayShadowDOM: false,
48+
excludeReplayCompressionWorker: false,
49+
},
50+
},
51+
});
52+
```
53+
54+
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.
55+
56+
The following sections cover each available tree-shaking option and how to configure them.
57+
58+
<SdkOption name="webpack.treeshake.removeDebugLogging" type="boolean" defaultValue="false">
59+
60+
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.
61+
62+
</SdkOption>
63+
64+
<SdkOption name="webpack.treeshake.removeTracing" type="boolean" defaultValue="false">
65+
66+
Setting this option to `true` will remove all code related to tracing and performance monitoring.
67+
68+
<Alert>
69+
You should not use any tracing-related SDK features (for example,
70+
`Sentry.startSpan()`) when this option is enabled. Also, this option has no
71+
effect if you did not add `browserTracingIntegration`.
72+
</Alert>
73+
74+
</SdkOption>
75+
76+
<SdkOption name="webpack.treeshake.excludeReplayIframe" type="boolean" defaultValue="false">
77+
78+
Setting this option to `true` will remove any SDK code related to capturing iframe content during [Session Replays](/platforms/javascript/session-replay/). This only applies when you've enabled `replayIntegration`.
79+
80+
</SdkOption>
81+
82+
<SdkOption name="webpack.treeshake.excludeReplayShadowDOM" type="boolean" defaultValue="false">
83+
84+
Setting this option to `true` will remove any SDK code related to capturing shadow DOM elements during [Session Replays](/platforms/javascript/session-replay/). This only applies when you've enabled `replayIntegration`.
85+
86+
</SdkOption>
87+
88+
<SdkOption name="webpack.treeshake.excludeReplayCompressionWorker" type="boolean" defaultValue="false">
89+
90+
Setting this option to `true` will remove any SDK code related to the included compression web worker for [Session Replay](/platforms/javascript/session-replay/). Enable this option 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 only applies when you've enabled `replayIntegration`.
91+
92+
**We don't recommend enabling this option unless you provide a custom worker URL**.
93+
94+
</SdkOption>
95+
96+
If you want to learn more about the available tree-shaking options and how to set them manually with different bundlers, see the [tree shaking documentation](/platforms/javascript/guides/react/configuration/tree-shaking/#tree-shaking-with-webpack) for the JavaScript SDK.

0 commit comments

Comments
 (0)