From fed5dbe0ab452f3534ae0dc75e8624f54ce0ba89 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Mon, 4 Apr 2022 17:57:10 +0200 Subject: [PATCH 1/6] Add guide for tree shaking in JavaScript --- .../common/troubleshooting/index.mdx | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/src/platforms/javascript/common/troubleshooting/index.mdx b/src/platforms/javascript/common/troubleshooting/index.mdx index 8c866fad58c87d..6ecbcbd7c518e8 100644 --- a/src/platforms/javascript/common/troubleshooting/index.mdx +++ b/src/platforms/javascript/common/troubleshooting/index.mdx @@ -403,3 +403,50 @@ document.body.addEventListener( ``` Remember to pass in `true` as the second parameter to `addEventListener()`. Without it, the event handler won't be called, since it's being added to the event target's ancestor rather than the event target itself, and unlike JavaScript runtime errors, `error` events resulting from load failures don't bubble, and therefore must be captured during the `capture` phase. For more information, see [the W3C spec](https://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/events.html#Events-phases). + +## Reducing Bundle Size + +Sentry ships with code that enables you to debug your Sentry configuration. While this code can be very useful in development environments, it is usually not necessary to include it in your production bundles where it takes up precious bytes. The JavaScript SDK uses special flags in its CommonJS and ESM distributions to facilitate tree-shaking of code sections that are used for debugging. Tree shaking is a way to remove unused code in your application during the build process. + +To mark any debug code as unused, we must replace debug flags in the sentry SDK with `false`. We outlined examples of how to do this in popular toolchains below. + +### Tree-shaking Debug Code 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/). Use it to replace all occurrences of the `__SENTRY_DEBUG__` flag with `false`: + +```javascript {filename:webpack.config.js} +const webpack = require("webpack"); + +module.exports = { + // ... other options + plugins: [ + new webpack.DefinePlugin({ + __SENTRY_DEBUG__: false, + }), + // ... other plugins + ], +}; +``` + +### Tree-shaking Debug Code with rollup.js + +If you are using rollup.js, we recommend [rollup's replace plugin](https://www.npmjs.com/package/@rollup/plugin-replace) to replace all occurrences of `__SENTRY_DEBUG__` with `false`: + +```javascript {filename:rollup.config.js} +import replace from "@rollup/plugin-replace"; +import { terser } from "rollup-plugin-terser"; + +export default { + // ... other options + treeshake: "smallest", // recommended for best tree shaking results + plugins: [ + replace({ + preventAssignment: false, + values: { + __SENTRY_DEBUG__: false, + }, + }), + // ... other plugins (best placed after) + ], +}; +``` From 5a55c67f61dd26ea7be7c017f62cc57925d24fc0 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Tue, 5 Apr 2022 08:40:14 +0200 Subject: [PATCH 2/6] Add tree shaking section for Next.js --- .../common/troubleshooting/index.mdx | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/src/platforms/javascript/common/troubleshooting/index.mdx b/src/platforms/javascript/common/troubleshooting/index.mdx index 6ecbcbd7c518e8..3b2c8e5941ed89 100644 --- a/src/platforms/javascript/common/troubleshooting/index.mdx +++ b/src/platforms/javascript/common/troubleshooting/index.mdx @@ -441,7 +441,7 @@ export default { treeshake: "smallest", // recommended for best tree shaking results plugins: [ replace({ - preventAssignment: false, + preventAssignment: false, // not necessary because flags are not assigned to values: { __SENTRY_DEBUG__: false, }, @@ -450,3 +450,28 @@ export default { ], }; ``` + + + +### Tree-shaking Debug 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/). The following Next.js configuration will replace all occurrences of `__SENTRY_DEBUG__` in your bundles with `false`: + +```javascript {filename:next.config.js} +const nextConfig = { + webpack: (config, { webpack }) => { + config.plugins.push( + new webpack.DefinePlugin({ + __SENTRY_DEBUG__: false, + }) + ); + + // 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. + + From 13ef01a4d1e88238e0144342049164286530d7c8 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Tue, 5 Apr 2022 17:14:13 +0200 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- .../common/troubleshooting/index.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/platforms/javascript/common/troubleshooting/index.mdx b/src/platforms/javascript/common/troubleshooting/index.mdx index 3b2c8e5941ed89..f35ce9b46c9b63 100644 --- a/src/platforms/javascript/common/troubleshooting/index.mdx +++ b/src/platforms/javascript/common/troubleshooting/index.mdx @@ -406,13 +406,13 @@ Remember to pass in `true` as the second parameter to `addEventListener()`. With ## Reducing Bundle Size -Sentry ships with code that enables you to debug your Sentry configuration. While this code can be very useful in development environments, it is usually not necessary to include it in your production bundles where it takes up precious bytes. The JavaScript SDK uses special flags in its CommonJS and ESM distributions to facilitate tree-shaking of code sections that are used for debugging. Tree shaking is a way to remove unused code in your application during the build process. +Sentry ships with code that enables you to debug your Sentry configuration. While this 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 uses special flags in its CommonJS and ESM distributions to facilitate tree shaking of code sections that are used for debugging. Tree shaking is a way to remove unused code in your application during the build process. -To mark any debug code as unused, we must replace debug flags in the sentry SDK with `false`. We outlined examples of how to do this in popular toolchains below. +To mark any debug code as unused, you must replace debug flags in the Sentry SDK with `false`. We've outlined examples of how to do this in popular toolchains below. -### Tree-shaking Debug Code with webpack +### Tree Shaking Debug Code 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/). Use it to replace all occurrences of the `__SENTRY_DEBUG__` flag with `false`: +To tree shake Sentry debug code in your webpack bundles, we recommend using webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/). Use it to replace all occurrences of the `__SENTRY_DEBUG__` flag with `false`: ```javascript {filename:webpack.config.js} const webpack = require("webpack"); @@ -428,9 +428,9 @@ module.exports = { }; ``` -### Tree-shaking Debug Code with rollup.js +### Tree Shaking Debug Code With rollup.js -If you are using rollup.js, we recommend [rollup's replace plugin](https://www.npmjs.com/package/@rollup/plugin-replace) to replace all occurrences of `__SENTRY_DEBUG__` with `false`: +If you're using rollup.js, we recommend [rollup's replace plugin](https://www.npmjs.com/package/@rollup/plugin-replace) to replace all occurrences of `__SENTRY_DEBUG__` with `false`: ```javascript {filename:rollup.config.js} import replace from "@rollup/plugin-replace"; @@ -453,9 +453,9 @@ export default { -### Tree-shaking Debug Code with Next.js +### Tree Shaking Debug 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/). The following Next.js configuration will replace all occurrences of `__SENTRY_DEBUG__` in your bundles with `false`: +To tree shake Sentry debug code in Next.js projects, you can use webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/). The following Next.js configuration will replace all occurrences of `__SENTRY_DEBUG__` in your bundles with `false`: ```javascript {filename:next.config.js} const nextConfig = { @@ -472,6 +472,6 @@ const nextConfig = { }; ``` -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. +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. From 41391dc7e2c7de38a69bd33e0cb7f8840d209cf7 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Tue, 5 Apr 2022 17:41:39 +0200 Subject: [PATCH 4/6] Show only next.js tree shaking section in next.js troubleshooting guide --- .../javascript/common/troubleshooting/index.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/platforms/javascript/common/troubleshooting/index.mdx b/src/platforms/javascript/common/troubleshooting/index.mdx index f35ce9b46c9b63..e9d4278f61d128 100644 --- a/src/platforms/javascript/common/troubleshooting/index.mdx +++ b/src/platforms/javascript/common/troubleshooting/index.mdx @@ -408,7 +408,11 @@ Remember to pass in `true` as the second parameter to `addEventListener()`. With Sentry ships with code that enables you to debug your Sentry configuration. While this 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 uses special flags in its CommonJS and ESM distributions to facilitate tree shaking of code sections that are used for debugging. Tree shaking is a way to remove unused code in your application during the build process. + To mark any debug code as unused, you must replace debug flags in the Sentry SDK with `false`. We've outlined examples of how to do this in popular toolchains below. + + + ### Tree Shaking Debug Code With webpack @@ -428,6 +432,10 @@ module.exports = { }; ``` + + + + ### Tree Shaking Debug Code With rollup.js If you're using rollup.js, we recommend [rollup's replace plugin](https://www.npmjs.com/package/@rollup/plugin-replace) to replace all occurrences of `__SENTRY_DEBUG__` with `false`: @@ -451,6 +459,8 @@ export default { }; ``` + + ### Tree Shaking Debug Code With Next.js From c96c94424b5b9bd48ce69e46b0c5f6c2fb956b3b Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 6 Apr 2022 09:51:43 +0200 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Katie Byers --- .../common/troubleshooting/index.mdx | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/src/platforms/javascript/common/troubleshooting/index.mdx b/src/platforms/javascript/common/troubleshooting/index.mdx index e9d4278f61d128..1510867bce7718 100644 --- a/src/platforms/javascript/common/troubleshooting/index.mdx +++ b/src/platforms/javascript/common/troubleshooting/index.mdx @@ -406,17 +406,17 @@ Remember to pass in `true` as the second parameter to `addEventListener()`. With ## Reducing Bundle Size -Sentry ships with code that enables you to debug your Sentry configuration. While this 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 uses special flags in its CommonJS and ESM distributions to facilitate tree shaking of code sections that are used for debugging. Tree shaking is a way to remove unused code in your application during the build process. +Sentry ships with code that enables you to debug your Sentry configuration, primarily through logging. While this 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 a special flag in its CommonJS and ESM distributions which can be used to facilitate [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) (removal) of such code during the build process. -To mark any debug code as unused, you must replace debug flags in the Sentry SDK with `false`. We've outlined examples of how to do this in popular toolchains below. +To make debugging code eligible for tree shaking, you must replace the `__SENTRY_DEBUG__` flag in the Sentry SDK with `false`. We've outlined examples of how to do this in popular toolchains below. -### Tree Shaking Debug Code With webpack +### Tree Shaking Debug Code 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/). Use it to replace all occurrences of the `__SENTRY_DEBUG__` flag with `false`: +To tree shake Sentry debug code in your webpack bundles, we recommend using webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/). ```javascript {filename:webpack.config.js} const webpack = require("webpack"); @@ -436,9 +436,9 @@ module.exports = { -### Tree Shaking Debug Code With rollup.js +### Tree Shaking Debug Code With Rollup -If you're using rollup.js, we recommend [rollup's replace plugin](https://www.npmjs.com/package/@rollup/plugin-replace) to replace all occurrences of `__SENTRY_DEBUG__` with `false`: +If you're using `rollup.js`, we recommend using [Rollup's `replace` plugin](https://github.com/rollup/plugins/tree/master/packages/replace). ```javascript {filename:rollup.config.js} import replace from "@rollup/plugin-replace"; @@ -449,10 +449,7 @@ export default { treeshake: "smallest", // recommended for best tree shaking results plugins: [ replace({ - preventAssignment: false, // not necessary because flags are not assigned to - values: { - __SENTRY_DEBUG__: false, - }, + __SENTRY_DEBUG__: false, }), // ... other plugins (best placed after) ], @@ -465,7 +462,7 @@ export default { ### Tree Shaking Debug 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/). The following Next.js configuration will replace all occurrences of `__SENTRY_DEBUG__` in your bundles with `false`: +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} const nextConfig = { From 870555456cf3847a457cd2f3b4abd9ec627fc1f7 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 6 Apr 2022 10:35:51 +0200 Subject: [PATCH 6/6] Move tree shaking tutorial to configuration --- .../configuration/tree-shaking/index.mdx | 81 +++++++++++++++++++ .../common/troubleshooting/index.mdx | 79 ------------------ 2 files changed, 81 insertions(+), 79 deletions(-) create mode 100644 src/platforms/javascript/common/configuration/tree-shaking/index.mdx diff --git a/src/platforms/javascript/common/configuration/tree-shaking/index.mdx b/src/platforms/javascript/common/configuration/tree-shaking/index.mdx new file mode 100644 index 00000000000000..18159d5c9f02f0 --- /dev/null +++ b/src/platforms/javascript/common/configuration/tree-shaking/index.mdx @@ -0,0 +1,81 @@ +--- +title: Tree Shaking +sidebar_order: 11000 +description: "Learn how to reduce Sentry bundle size by tree shaking unused code." +keywords: ["bundle size", "webpack", "rollup", "debug"] +--- + +Sentry ships with code that enables you to debug your Sentry configuration, primarily through logging. While this 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 a special flag in its CommonJS and ESM distributions which can be used to facilitate [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) (removal) of such code during the build process. + +To make debugging code eligible for tree shaking, you must replace the `__SENTRY_DEBUG__` flag in the Sentry SDK with `false`. + + + +## Tree Shaking Debug Code 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/). + +```javascript {filename:webpack.config.js} +const webpack = require("webpack"); + +module.exports = { + // ... other options + plugins: [ + new webpack.DefinePlugin({ + __SENTRY_DEBUG__: false, + }), + // ... other plugins + ], +}; +``` + + + + + +## Tree Shaking Debug Code With Rollup + +If you're using `rollup.js`, we recommend using [Rollup's `replace` plugin](https://github.com/rollup/plugins/tree/master/packages/replace). + +```javascript {filename:rollup.config.js} +import replace from "@rollup/plugin-replace"; +import { terser } from "rollup-plugin-terser"; + +export default { + // ... other options + treeshake: "smallest", // recommended for best tree shaking results + plugins: [ + replace({ + __SENTRY_DEBUG__: false, + }), + // ... other plugins (best placed after) + ], +}; +``` + + + + + +## Tree Shaking Debug 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} +const nextConfig = { + webpack: (config, { webpack }) => { + config.plugins.push( + new webpack.DefinePlugin({ + __SENTRY_DEBUG__: false, + }) + ); + + // 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. + + diff --git a/src/platforms/javascript/common/troubleshooting/index.mdx b/src/platforms/javascript/common/troubleshooting/index.mdx index 1510867bce7718..8c866fad58c87d 100644 --- a/src/platforms/javascript/common/troubleshooting/index.mdx +++ b/src/platforms/javascript/common/troubleshooting/index.mdx @@ -403,82 +403,3 @@ document.body.addEventListener( ``` Remember to pass in `true` as the second parameter to `addEventListener()`. Without it, the event handler won't be called, since it's being added to the event target's ancestor rather than the event target itself, and unlike JavaScript runtime errors, `error` events resulting from load failures don't bubble, and therefore must be captured during the `capture` phase. For more information, see [the W3C spec](https://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/events.html#Events-phases). - -## Reducing Bundle Size - -Sentry ships with code that enables you to debug your Sentry configuration, primarily through logging. While this 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 a special flag in its CommonJS and ESM distributions which can be used to facilitate [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) (removal) of such code during the build process. - - -To make debugging code eligible for tree shaking, you must replace the `__SENTRY_DEBUG__` flag in the Sentry SDK with `false`. We've outlined examples of how to do this in popular toolchains below. - - - - -### Tree Shaking Debug Code 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/). - -```javascript {filename:webpack.config.js} -const webpack = require("webpack"); - -module.exports = { - // ... other options - plugins: [ - new webpack.DefinePlugin({ - __SENTRY_DEBUG__: false, - }), - // ... other plugins - ], -}; -``` - - - - - -### Tree Shaking Debug Code With Rollup - -If you're using `rollup.js`, we recommend using [Rollup's `replace` plugin](https://github.com/rollup/plugins/tree/master/packages/replace). - -```javascript {filename:rollup.config.js} -import replace from "@rollup/plugin-replace"; -import { terser } from "rollup-plugin-terser"; - -export default { - // ... other options - treeshake: "smallest", // recommended for best tree shaking results - plugins: [ - replace({ - __SENTRY_DEBUG__: false, - }), - // ... other plugins (best placed after) - ], -}; -``` - - - - - -### Tree Shaking Debug 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} -const nextConfig = { - webpack: (config, { webpack }) => { - config.plugins.push( - new webpack.DefinePlugin({ - __SENTRY_DEBUG__: false, - }) - ); - - // 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. - -