Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/getsentry/sentry-javascript/llms.txt

Use this file to discover all available pages before exploring further.

This guide provides a detailed look at how individual packages are structured, configured, and built within the Sentry JavaScript SDK monorepo.

​
Package Anatomy

Every package in the monorepo follows a consistent structure. Let’s examine @sentry/core as an example.

​
Directory Structure

packages/core/
├── src/                          # Source TypeScript files
│   ├── index.ts                 # Main entry point (exports public API)
│   ├── hub.ts                   # Hub implementation
│   ├── scope.ts                 # Scope implementation
│   ├── client.ts                # Base client
│   ├── integration.ts           # Integration interface
│   ├── tracing/                 # Performance monitoring
│   │   ├── index.ts
│   │   ├── span.ts
│   │   └── ...
│   ├── utils/                   # Internal utilities
│   └── types/                   # Type definitions
├── test/                         # Test files mirror src/ structure
│   ├── lib/
│   │   ├── hub.test.ts
│   │   ├── scope.test.ts
│   │   └── ...
│   └── integration/
├── build/                        # Build output (gitignored)
│   ├── cjs/                     # CommonJS build
│   ├── esm/                     # ES modules build
│   ├── types/                   # TypeScript definitions
│   └── types-ts3.8/             # Downleveled types
├── package.json                  # Package configuration
├── tsconfig.json                 # TypeScript config
├── tsconfig.types.json           # Config for type generation
├── rollup.npm.config.mjs         # Rollup build config
├── vitest.config.ts              # Test configuration
└── README.md                     # Package documentation

​
package.json Configuration

Here’s the package.json for @sentry/core with annotations: 
{
  "name": "@sentry/core",
  "version": "10.42.0",
  "description": "Base implementation for all Sentry JavaScript SDKs",
  "repository": "git://github.com/getsentry/sentry-javascript.git",
  "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/core",
  "author": "Sentry",
  "license": "MIT",
  "engines": {
    "node": ">=18"
  },
  "files": [
    "/build"  // Only publish build directory
  ],
  
  // Entry points for different module systems
  "main": "build/cjs/index.js",
  "module": "build/esm/index.js",
  "types": "build/types/index.d.ts",
  
  // Modern entry points with conditional exports
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "import": {
        "types": "./build/types/index.d.ts",
        "default": "./build/esm/index.js"
      },
      "require": {
        "types": "./build/types/index.d.ts",
        "default": "./build/cjs/index.js"
      }
    }
  },
  
  // TypeScript version compatibility
  "typesVersions": {
    "<5.0": {
      "build/types/index.d.ts": [
        "build/types-ts3.8/index.d.ts"
      ]
    }
  },
  
  "publishConfig": {
    "access": "public"
  },
  
  // Build and test scripts
  "scripts": {
    "build": "run-p build:transpile build:types",
    "build:dev": "yarn build",
    "build:transpile": "rollup -c rollup.npm.config.mjs",
    "build:types": "run-s build:types:core build:types:downlevel",
    "build:types:core": "tsc -p tsconfig.types.json",
    "build:types:downlevel": "yarn downlevel-dts build/types build/types-ts3.8 --to ts3.8",
    "build:watch": "run-p build:transpile:watch",
    "build:dev:watch": "yarn build:watch",
    "build:transpile:watch": "rollup -c rollup.npm.config.mjs --watch",
    "build:tarball": "npm pack",
    "circularDepCheck": "madge --circular src/index.ts",
    "clean": "rimraf build coverage sentry-core-*.tgz",
    "fix": "eslint . --format stylish --fix",
    "lint": "eslint . --format stylish",
    "test": "vitest run",
    "test:watch": "vitest --watch",
    "yalc:publish": "yalc publish --push --sig"
  },
  
  // Inherit Volta versions from root
  "volta": {
    "extends": "../../package.json"
  },
  
  "sideEffects": false,
  
  "devDependencies": {
    "zod": "^3.24.1"
  }
}

​
TypeScript Configuration

​
Main Config (tsconfig.json)

Used for IDE support and linting: 
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "build",
    "rootDir": "src",
    "baseUrl": "src",
    "paths": {
      "@sentry/core": ["./src/index.ts"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["test/**/*"]
}

​
Types Config (tsconfig.types.json)

Used for generating .d.ts files: 
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "emitDeclarationOnly": true,
    "outDir": "build/types"
  }
}

​
Build Configuration

​
Rollup Config (rollup.npm.config.mjs)

Packages use Rollup for transpilation: 
import { makeBaseBundleConfig, makeConfigVariants } from '../../dev-packages/rollup-utils';

export default makeConfigVariants(
  makeBaseBundleConfig({
    // Entry point
    input: 'src/index.ts',
    
    // Output both CJS and ESM
    output: [
      { format: 'cjs', dir: 'build/cjs' },
      { format: 'esm', dir: 'build/esm' },
    ],
    
    // External dependencies (not bundled)
    external: [
      // All dependencies from package.json
    ],
  }),
);
The rollup-utils package in dev-packages/ provides shared Rollup configuration.

​
Build Process

When you run yarn build:dev in a package:

​
1. TypeScript Type Generation

tsc -p tsconfig.types.json
Outputs: 
build/types/
├── index.d.ts
├── hub.d.ts
├── scope.d.ts
└── ...

​
2. Downlevel Types for TS 3.8

downlevel-dts build/types build/types-ts3.8 --to ts3.8
Outputs: 
build/types-ts3.8/
├── index.d.ts
├── hub.d.ts
└── ...

​
3. Rollup Transpilation

rollup -c rollup.npm.config.mjs
Outputs: 
build/cjs/
├── index.js
├── hub.js
└── ...

build/esm/
├── index.js
├── hub.js
└── ...

​
Package Categories

​
Core Packages

Minimal dependencies, provide foundation: @sentry/core - Base SDK
  • No external dependencies
  • Provides: Hub, Scope, Client, Integrations
  • Used by: All platform and framework SDKs
@sentry/browser-utils - Browser utilities
  • Dependencies: @sentry/core
  • Provides: DOM utilities, fetch/XHR instrumentation
  • Used by: Browser-based SDKs
@sentry/node-core - Node core
  • Dependencies: @sentry/core
  • Provides: Node.js-specific functionality (without OTel)
  • Used by: @sentry/node and serverless SDKs

​
Platform SDKs

@sentry/browser
  • Dependencies: @sentry/core, @sentry/browser-utils
  • Provides: Browser SDK, CDN bundles
  • Special build: build:bundle creates CDN bundles
@sentry/node
  • Dependencies: @sentry/core, @sentry/node-core, @sentry/opentelemetry
  • Provides: Node.js SDK with OpenTelemetry instrumentation
  • Includes: HTTP, database, and framework integrations
@sentry/bun
  • Dependencies: @sentry/core, @sentry/node-core
  • Provides: Bun runtime SDK
@sentry/deno
  • Dependencies: @sentry/core, @sentry/browser-utils
  • Provides: Deno runtime SDK
@sentry/cloudflare
  • Dependencies: @sentry/core
  • Provides: Cloudflare Workers SDK
  • Edge runtime compatible

​
Framework Integrations

@sentry/react
  • Dependencies: @sentry/browser, @sentry/core
  • Provides: Error boundary, hooks, React Router integration
  • Peer dependencies: react
@sentry/nextjs
  • Dependencies: @sentry/node, @sentry/react, @sentry/browser
  • Provides: Next.js SDK with client/server integration
  • Special: Has client, server, and edge entry points
  • Build config: Webpack plugins for instrumentation
@sentry/vue
  • Dependencies: @sentry/browser, @sentry/core
  • Provides: Vue error handler, Vue Router integration
  • Peer dependencies: vue
@sentry/sveltekit
  • Dependencies: @sentry/node, @sentry/svelte, @sentry/browser
  • Provides: SvelteKit SDK with client/server
  • Special: Vite plugins for instrumentation

​
Special Build Targets

​
CDN Bundles (Browser Only)

The @sentry/browser package creates CDN bundles: 
yarn build:bundle
Outputs: 
build/bundles/
├── bundle.min.js              # Full SDK
├── bundle.min.js.map
├── bundle.tracing.min.js      # SDK + Tracing
├── bundle.replay.min.js       # SDK + Replay
└── ...
These are uploaded to https://browser.sentry-cdn.com/.

​
Lambda Layers (AWS Serverless)

The @sentry/aws-serverless package creates Lambda layers: 
yarn build:layer

​
Browser Bundles with Integrations

Some bundles include specific integrations pre-configured.

​
Testing Setup

​
Vitest Configuration

Packages use Vitest for testing: 
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node', // or 'jsdom' for browser packages
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
    },
  },
});

​
Test Structure

Tests mirror the source structure: 
src/hub.ts → test/lib/hub.test.ts
src/scope.ts → test/lib/scope.test.ts

​
Circular Dependency Checking

Each package can check for circular dependencies: 
yarn circularDepCheck
This runs Madge on the package: 
madge --circular src/index.ts

​
Package Dependencies

​
Internal Dependencies

Use workspace protocol: 
"dependencies": {
  "@sentry/core": "workspace:*",
  "@sentry/browser": "workspace:*"
}

​
External Dependencies

Minimize external dependencies to reduce bundle size: 
"dependencies": {
  "@opentelemetry/api": "^1.0.0"
}

​
Peer Dependencies

Framework integrations specify peer dependencies: 
"peerDependencies": {
  "react": ">=16.0.0"
},
"peerDependenciesMeta": {
  "react": {
    "optional": false
  }
}

​
Publishing

Packages are published to npm with: 
"publishConfig": {
  "access": "public"
}
Only the build/ directory is published: 
"files": ["/build"]

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us