Bundle Size Optimization

The Sentry JavaScript SDK is designed to be lightweight, but you can further optimize bundle size by customizing integrations and using tree-shaking.

Bundle Size Impact

Typical bundle sizes (gzipped):

Browser SDK (minimal): ~25 KB
Browser SDK (with integrations): ~35-45 KB
Node SDK: Not relevant for frontend bundles
Framework SDKs: Similar to Browser SDK + framework-specific code

The SDK’s bundle size impact is usually minimal compared to other dependencies like React, Vue, or large utility libraries.

Tree-Shaking

Modern bundlers automatically remove unused code:

// ✅ Good: Named imports enable tree-shaking
import { init, browserTracingIntegration } from '@sentry/browser';

init({
  dsn: '__DSN__',
  integrations: [browserTracingIntegration()],
});

// ❌ Bad: Namespace imports may include more code
import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: '__DSN__',
  integrations: [Sentry.browserTracingIntegration()],
});

While namespace imports (import * as Sentry) are convenient and recommended for better DX, named imports (import { init }) may result in slightly smaller bundles with some bundlers.

Selective Integration Loading

Minimal SDK

Disable default integrations and add only what you need:

import {
  init,
  globalHandlersIntegration,
  breadcrumbsIntegration,
} from '@sentry/browser';

init({
  dsn: '__DSN__',
  defaultIntegrations: false, // Disable all defaults
  integrations: [
    // Add only what you need
    globalHandlersIntegration(),
    breadcrumbsIntegration(),
  ],
});

Conditional Integration Loading

Load heavy integrations only when needed:

import { init } from '@sentry/browser';

const integrations = [];

// Always include core integrations
import { globalHandlersIntegration } from '@sentry/browser';
integrations.push(globalHandlersIntegration());

// Conditionally add Replay (larger bundle)
if (shouldEnableReplay) {
  const { replayIntegration } = await import('@sentry-internal/replay');
  integrations.push(replayIntegration());
}

init({
  dsn: '__DSN__',
  integrations,
});

Lazy Loading Sentry

Load Sentry asynchronously to improve initial page load:

// Load Sentry after initial render
window.addEventListener('load', async () => {
  const Sentry = await import('@sentry/browser');
  
  Sentry.init({
    dsn: '__DSN__',
  });
});

Lazy loading means errors during initial page load won’t be captured. Only use this if initial load performance is critical.

Smart Lazy Loading

Load immediately on errors, lazily otherwise:

let sentryLoaded = false;

async function loadSentry() {
  if (sentryLoaded) return;
  
  const Sentry = await import('@sentry/browser');
  Sentry.init({ dsn: '__DSN__' });
  sentryLoaded = true;
}

// Load on error
window.addEventListener('error', loadSentry);
window.addEventListener('unhandledrejection', loadSentry);

// Load after idle
if ('requestIdleCallback' in window) {
  requestIdleCallback(loadSentry);
} else {
  setTimeout(loadSentry, 1000);
}

CDN Loading

Use the Sentry CDN bundle to avoid bundling:

<script
  src="https://browser.sentry-cdn.com/8.0.0/bundle.tracing.replay.min.js"
  integrity="sha384-..."
  crossorigin="anonymous"
></script>

<script>
  Sentry.init({
    dsn: '__DSN__',
  });
</script>

Available CDN Bundles

<!-- Minimal bundle -->
<script src="https://browser.sentry-cdn.com/8.0.0/bundle.min.js"></script>

<!-- With performance monitoring -->
<script src="https://browser.sentry-cdn.com/8.0.0/bundle.tracing.min.js"></script>

<!-- With session replay -->
<script src="https://browser.sentry-cdn.com/8.0.0/bundle.replay.min.js"></script>

<!-- With both -->
<script src="https://browser.sentry-cdn.com/8.0.0/bundle.tracing.replay.min.js"></script>

<!-- With feedback widget -->
<script src="https://browser.sentry-cdn.com/8.0.0/bundle.feedback.min.js"></script>

Framework-Specific Optimizations

React

Only import what you need:

import { init, reactRouterV6BrowserTracingIntegration } from '@sentry/react';
import { useEffect } from 'react';
import {
  useLocation,
  useNavigationType,
  createRoutesFromChildren,
  matchRoutes,
} from 'react-router-dom';

init({
  dsn: '__DSN__',
  integrations: [
    reactRouterV6BrowserTracingIntegration({
      useEffect,
      useLocation,
      useNavigationType,
      createRoutesFromChildren,
      matchRoutes,
    }),
  ],
});

Next.js

Next.js SDK is optimized automatically:

// sentry.client.config.ts
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: '__DSN__',
  // Tree-shaking happens automatically
});

Further optimization:

// next.config.js
const { withSentryConfig } = require('@sentry/nextjs');

module.exports = withSentryConfig(
  {
    // Next.js config
  },
  {
    // Sentry config
    silent: true,
    
    // Exclude source maps from bundle
    widenClientFileUpload: true,
    hideSourceMaps: true, // Available in v7
  }
);

Vue

import { init, browserTracingIntegration } from '@sentry/vue';

init({
  app,
  dsn: '__DSN__',
  integrations: [
    browserTracingIntegration({ router }), // Only if using Vue Router
  ],
});

Bundler Configuration

Webpack

Optimize tree-shaking:

// webpack.config.js
module.exports = {
  optimization: {
    usedExports: true,
    sideEffects: false,
  },
};

Vite

Vite optimizes automatically, but you can verify:

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // Separate Sentry into its own chunk
          sentry: ['@sentry/browser'],
        },
      },
    },
  },
});

Rollup

// rollup.config.js
import { terser } from 'rollup-plugin-terser';

export default {
  plugins: [
    terser({
      compress: {
        pure_funcs: ['console.log'], // Remove debug logs
      },
    }),
  ],
};

Feature Flags for Bundle Size

Disable Debug Code in Production

The SDK includes debug code that’s stripped in production:

import { init } from '@sentry/browser';

init({
  dsn: '__DSN__',
  debug: false, // Ensure debug is off in production
});

Environment-Based Loading

if (process.env.NODE_ENV === 'production') {
  import('@sentry/browser').then((Sentry) => {
    Sentry.init({ dsn: '__DSN__' });
  });
}

Measuring Bundle Size

webpack-bundle-analyzer

npm install --save-dev webpack-bundle-analyzer

// webpack.config.js
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin(),
  ],
};

Vite Plugin Visualizer

npm install --save-dev rollup-plugin-visualizer

// vite.config.js
import { visualizer } from 'rollup-plugin-visualizer';

export default {
  plugins: [
    visualizer({ open: true }),
  ],
};

Bundle Size Limit

Set size limits to prevent regressions:

npm install --save-dev size-limit @size-limit/preset-app

// package.json
{
  "size-limit": [
    {
      "path": "dist/bundle.js",
      "limit": "100 KB"
    }
  ]
}

Integration Size Reference

Approximate sizes (gzipped):

Integration	Size	When to Use
Core SDK	~25 KB	Always
browserTracingIntegration	~8 KB	Performance monitoring
replayIntegration	~35 KB	Session replay
feedbackIntegration	~15 KB	User feedback
replayCanvasIntegration	~10 KB	Canvas recording in replay
captureConsoleIntegration	~2 KB	Console log capture
httpClientIntegration	~3 KB	HTTP breadcrumbs

Best Practices

Audit integrations regularly

Review which integrations you’re using and remove unused ones:

// Review this list periodically
const integrations = [
  globalHandlersIntegration(),     // ✅ Needed
  breadcrumbsIntegration(),        // ✅ Needed
  browserTracingIntegration(),     // ❓ Still using?
  replayIntegration(),             // ❓ Still needed?
];

Use code splitting for heavy features

Load heavy integrations dynamically:

// Only load replay when needed
async function enableReplay() {
  const { replayIntegration } = await import('@sentry-internal/replay');
  const client = Sentry.getClient();
  client.addIntegration(replayIntegration());
}

Consider CDN for prototyping

During development, use CDN bundles to avoid build config:

<!-- Quick setup -->
<script src="https://browser.sentry-cdn.com/8.0.0/bundle.min.js"></script>

Switch to npm package for production for better bundling control.

Monitor bundle size in CI

Add bundle size checks to prevent regressions:

npm run size-limit

Don't over-optimize at the expense of functionality

The SDK’s impact is usually minimal. Removing error reporting to save 25 KB is rarely worth it.

Complete Minimal Example

// Smallest possible Sentry setup
import {
  init,
  createTransport,
  makeFetchTransport,
} from '@sentry/browser';

init({
  dsn: '__DSN__',
  
  // Disable all default integrations
  defaultIntegrations: false,
  
  // Minimal transport
  transport: makeFetchTransport,
  
  // No performance monitoring
  enableTracing: false,
});

// This setup is < 20 KB gzipped
// Only captures manually sent events

Production-Optimized Example

import {
  init,
  browserTracingIntegration,
  globalHandlersIntegration,
  breadcrumbsIntegration,
  dedupeIntegration,
} from '@sentry/browser';

const isProd = process.env.NODE_ENV === 'production';

init({
  dsn: '__DSN__',
  environment: process.env.NODE_ENV,
  debug: !isProd,
  
  // Only essential integrations
  defaultIntegrations: false,
  integrations: [
    globalHandlersIntegration(),
    breadcrumbsIntegration(),
    dedupeIntegration(),
    browserTracingIntegration(),
  ],
  
  // Lower sampling in production
  tracesSampleRate: isProd ? 0.05 : 1.0,
  
  // Minimal breadcrumbs
  maxBreadcrumbs: 25,
});

// Load replay only when needed
if (userWantsReplay) {
  import('@sentry-internal/replay').then(({ replayIntegration }) => {
    Sentry.getClient().addIntegration(replayIntegration());
  });
}

// ~30 KB gzipped with tracing, ~25 KB without

Configuration

Best Practices

Migration

Advanced

Bundle Size Impact

Tree-Shaking

Selective Integration Loading

Minimal SDK

Conditional Integration Loading

Lazy Loading Sentry

Smart Lazy Loading

CDN Loading

Available CDN Bundles

Framework-Specific Optimizations

React

Next.js

Vue

Bundler Configuration

Webpack

Vite

Rollup

Feature Flags for Bundle Size

Disable Debug Code in Production

Environment-Based Loading

Measuring Bundle Size

webpack-bundle-analyzer

Vite Plugin Visualizer

Bundle Size Limit

Integration Size Reference

Best Practices

Complete Minimal Example

Production-Optimized Example

Next Steps

Source Maps

Performance Monitoring

Configuration

Best Practices

Migration

Advanced

​Bundle Size Impact

​Tree-Shaking

​Selective Integration Loading

​Minimal SDK

​Conditional Integration Loading

​Lazy Loading Sentry

​Smart Lazy Loading

​CDN Loading

​Available CDN Bundles

​Framework-Specific Optimizations

​React

​Next.js

​Vue

​Bundler Configuration

​Webpack

​Vite

​Rollup

​Feature Flags for Bundle Size

​Disable Debug Code in Production

​Environment-Based Loading

​Measuring Bundle Size

​webpack-bundle-analyzer

​Vite Plugin Visualizer

​Bundle Size Limit

​Integration Size Reference

​Best Practices

​Complete Minimal Example

​Production-Optimized Example

​Next Steps

Source Maps

Performance Monitoring

Bundle Size Impact

Tree-Shaking

Selective Integration Loading

Minimal SDK

Conditional Integration Loading

Lazy Loading Sentry

Smart Lazy Loading

CDN Loading

Available CDN Bundles

Framework-Specific Optimizations

React

Next.js

Vue

Bundler Configuration

Webpack

Vite

Rollup

Feature Flags for Bundle Size

Disable Debug Code in Production

Environment-Based Loading

Measuring Bundle Size

webpack-bundle-analyzer

Vite Plugin Visualizer

Bundle Size Limit

Integration Size Reference

Best Practices

Complete Minimal Example

Production-Optimized Example

Next Steps