Skip to content

feat(js): Restructure tree shaking docs #9654

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 17, 2024
Merged

feat(js): Restructure tree shaking docs #9654

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3686ba0
feat(js): Restructure tree shaking docs
mydea Apr 10, 2024
59438a4
Apply suggestions from code review
mydea Apr 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 70 additions & 64 deletions docs/platforms/javascript/common/configuration/tree-shaking/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,40 +23,10 @@ The Sentry SDK ships with code that is not strictly required for it to collect y
you use certain features.
</Note>

### List Of Flags

To make optional code eligible for tree shaking, you can remove the code from your build output by replacing various flags in the Sentry SDK.

The following flags are available:

`__SENTRY_DEBUG__`

Replacing this flag with `false` will tree shake all code in the SDK that is related to debug logging.

`__SENTRY_TRACING__`

Replacing this flag with `false` will tree shake all code in the SDK that is related to performance monitoring.
**Attention:** `__SENTRY_TRACING__` must not be replaced with `false` when you're using any performance monitoring-related SDK features (e.g. `Sentry.startTransaction()`). This flag is intended to be used in combination with packages like `@sentry/next` or `@sentry/sveltekit`, which automatically include performance monitoring functionality.

<PlatformSection notSupported={["javascript.wasm", "javascript.cordova", "javascript.bun", "javascript.deno"]}>

`__RRWEB_EXCLUDE_IFRAME__`

Replacing this flag with `true` will tree shake all code in the SDK that is related capturing iframe content with Session Replay. This is only relevant when using <PlatformLink to="/session-replay">Session Replay</PlatformLink>. You can enable this flag if you don't have any iframes on your page you care to record.

`__RRWEB_EXCLUDE_SHADOW_DOM__`

Replacing this flag with `true` will tree shake all code in the SDK that's related to capturing shadow dom elements with Session Replay. This is only relevant when using <PlatformLink to="/session-replay">Session Replay</PlatformLink>. Enable this flag if you don't have any shadow dom elements on your page you want to record.

`__SENTRY_EXCLUDE_REPLAY_WORKER__`

Replacing this flag with `true` will tree shake all code in the SDK that's related to the included compression web worker for Session Replay. This is only relevant when using <PlatformLink to="/session-replay">Session Replay</PlatformLink>. Enable this flag if you want to host a compression worker yourself - see <PlatformLink to="/session-replay/configuration/#using-a-custom-compression-worker">Using a Custom Compression Worker</PlatformLink> for details. **We do not recommend enabling this flag unless you provide a custom worker URL.**

</PlatformSection>

<PlatformSection notSupported={["javascript.nextjs", "javascript.sveltekit", "javascript.remix", "javascript.astro"]}>

### Tree Shaking Optional Code With Sentry Bundler Plugins
### Tree Shaking With Sentry Bundler Plugins

_This configuration is available starting with v2.9.0 of the bundler plugins._

Expand Down Expand Up @@ -85,9 +55,73 @@ For more details, see the documentation for the specific bundler plugin you're u

</PlatformSection>


<PlatformSection supported={["javascript.nextjs"]}>

### 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.

</PlatformSection>

### 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.

**The following flags are available:**

`__SENTRY_DEBUG__`

Replacing this flag with `false` will tree shake any SDK code that's related to debug logging.

`__SENTRY_TRACING__`

Replacing this flag with `false` will tree shake any SDK code that's related to performance monitoring.

<Note>
`__SENTRY_TRACING__` must not be replaced with `false` when you're using any performance monitoring-related SDK features (for example,`Sentry.startTransaction()`). This flag is intended to be used in combination with packages like `@sentry/next` or `@sentry/sveltekit`, which automatically include the performance monitoring functionality.
</Note>

<PlatformSection notSupported={["javascript.wasm", "javascript.cordova", "javascript.bun", "javascript.deno"]}>

`__RRWEB_EXCLUDE_IFRAME__`

Replacing this flag with `true` will tree shake any SDK code related to capturing iframe content with Session Replay. It's only relevant when using <PlatformLink to="/session-replay">Session Replay</PlatformLink>. Enable this flag if you don't want to record any iframes.

`__RRWEB_EXCLUDE_SHADOW_DOM__`

Replacing this flag with `true` will tree shake any SDK code related to capturing shadow dom elements with Session Replay. It's only relevant when using <PlatformLink to="/session-replay">Session Replay</PlatformLink>. Enable this flag if you don't want to record any shadow dom elements.

`__SENTRY_EXCLUDE_REPLAY_WORKER__`

Replacing this flag with `true` will tree shake any SDK code that's related to the included compression web worker for Session Replay. It's only relevant when using <PlatformLink to="/session-replay">Session Replay</PlatformLink>. Enable this flag if you want to host a compression worker yourself. See <PlatformLink to="/session-replay/configuration/#using-a-custom-compression-worker">Using a Custom Compression Worker</PlatformLink> for details. **We don't recommend enabling this flag unless you provide a custom worker URL.**

</PlatformSection>

<PlatformSection notSupported={["javascript.nextjs", "javascript.sveltekit", "javascript.remix", "javascript.astro"]}>

### Tree Shaking Optional Code With Webpack
### Tree Shaking With Webpack

To tree shake Sentry debug code in your webpack bundles, we recommend using webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/):

Expand All @@ -113,7 +147,7 @@ module.exports = {

<PlatformSection notSupported={["javascript.nextjs", "javascript.sveltekit", "javascript.remix", "javascript.astro"]}>

### Tree Shaking Optional Code With Rollup
### Tree Shaking With Rollup

If you're using `rollup.js`, we recommend using [Rollup's `replace` plugin](https://github.com/rollup/plugins/tree/master/packages/replace):

Expand All @@ -139,35 +173,6 @@ export default {

</PlatformSection>

<PlatformSection supported={["javascript.nextjs"]}>

### Tree Shaking Optional Code With Next.js

To tree shake Sentry debug code in Next.js projects, you can use webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/) in your Next.js configuration.

```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.

</PlatformSection>

## Tree Shaking Default Integrations

By default, the Sentry SDK sets up a list of [default integrations](../integrations) that extend your
Expand All @@ -186,7 +191,7 @@ import {
breadcrumbsIntegration,
dedupeIntegration,
defaultStackParser,
getCurrentHub,
getCurrentScope,
globalHandlersIntegration,
makeFetchTransport,
linkedErrorsIntegration,
Expand All @@ -207,7 +212,8 @@ const client = new BrowserClient({
],
});

getCurrentHub().bindClient(client);
getCurrentScope().setClient(client);
client.init();
```

<Note>
Expand Down
Loading