Add guide for tree shaking in JavaScript (#4900)

Co-authored-by: Isabel <[email protected]>
Co-authored-by: Katie Byers <[email protected]>

Author: 3 people

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`.
+
+<PlatformSection notSupported={["javascript.nextjs"]}>
+
+## 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
+  ],
+};
+```
+
+</PlatformSection>
+
+<PlatformSection notSupported={["javascript.nextjs"]}>
+
+## 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)
+  ],
+};
+```
+
+</PlatformSection>
+
+<PlatformSection supported={["javascript.nextjs"]}>
+
+## 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.
+
+</PlatformSection>