# getsentry/sentry-javascript architecture

> Architecture diagram of the GitHub repository getsentry/sentry-javascript, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/getsentry/sentry-javascript
- Repository: https://github.com/getsentry/sentry-javascript

## Overview

##### Project type and purpose
- This is an open‑source monorepo (managed by Lerna/Nx + Yarn Workspaces) hosting the Official Sentry SDKs for JavaScript.
- Purpose: publish a family of platform‑specific SDKs (browser, node, React, Angular, Next.js, etc.) plus shared core libraries and test harnesses.

##### High‑level components
a. Root Workspace
- Contains global configuration: lerna.json, nx.json, package.json, tsconfig.json, .github workflows, docs/, scripts/.
- Orchestrates multi‑package build, test, and release via GitHub Actions and custom scripts.
b. packages/
- “@sentry/core”: base SDK interfaces, envelope builder, transport abstractions, event processing, tracing engine.
- “@sentry/browser”, “@sentry/node”, “@sentry/react”, etc.: high‑level platform SDKs.
- Shared packages: browser‑utils (web vitals, instrumentation wrappers), integration‑shims, types, profiling, cloudflare, aws‑serverless, deno, bun, etc.
c. dev‑packages/
- E2E and unit test harnesses: Playwright and custom fixtures for browser integration tests (dev‑packages/browser‑integration‑tests).
- node‑integration‑tests: scripts and scenarios for server‑side SDK tests.
- bundle‑analyzer‑scenarios, clear‑cache‑GH‑actions, external‑contributor actions, size‑limit actions.
d. docs/
- Markdown guides for contributors, platform support, migration, architecture notes.
e. CI/CD pipeline
- .github/workflows: build, test, lint, code‑scanning (CodeQL), auto‑release, canary deploys, cache management.

##### Relationships and interactions
- Each platform SDK in packages/ imports from @sentry/core and often from browser‑utils or integration‑shims.
- Shared utilities flow “downward” (core → higher‑level SDKs).
- dev‑packages and packages/*/test drive test suites; they depend on built output of packages/*.
- scripts/ and .github/actions define build/test/publish pipelines that operate on all packages.
- Git tags/trunk trigger publishing each package to npm with proper versioning.

##### Architectural patterns and design principles
- Monorepo with workspace‑level orchestration (Lerna/Nx, Yarn Workspaces).
- Modular “package per responsibility” pattern—each SDK and utility is its own npm package.
- Shared core fosters consistency and DRY across SDKs; extension via integration‑shims.
- CI pipeline enforces reproducible builds, automated releases, and e2e matrix testing across JavaScript frameworks.

##### Technologies, frameworks, libraries
- TypeScript for source and definitions.
- Rollup + Vite for bundling and ESM/CJS outputs.
- Jest/Vitest for unit tests and Playwright for browser e2e.
- GitHub Actions for CI workflows and release automation.
- CodeQL, Dependabot, Dependabot‑review, and size‑limit for quality and security.

b. Inside, partition into:
- "packages/" (group of sub‑containers for core, browser, node, framework SDKs, shared utils)
- "dev‑packages/" (test harnesses and CI actions)
- "docs/" + "scripts/" + ".github/"

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "getsentry/sentry-javascript (monorepo)"
    subgraph "Root Configuration"
      Lerna["lerna.json"]:::config
      Nx["nx.json"]:::config
      PkgRoot["package.json"]:::config
      TsCfg["tsconfig.json"]:::config
      GitHubCfg[".github/"]:::config
      DocsRoot["docs/"]:::config
      Scripts["scripts/"]:::config
    end

    subgraph "packages/"
      Core["@sentry/core"]:::coregreen
      Browser["@sentry/browser"]:::sdkblue
      Node["@sentry/node"]:::sdkblue
      React["@sentry/react"]:::sdkblue
      Angular["@sentry/angular"]:::sdkblue
      Nextjs["@sentry/nextjs"]:::sdkblue
      BrUtils["@sentry/browser-utils"]:::utilgreen
      Shims["@sentry/integration-shims"]:::utilgreen
      Deno["@sentry/deno"]:::sdkblue
      Bun["@sentry/bun"]:::sdkblue
      Cloudflare["@sentry/cloudflare"]:::sdkblue
      AWS["@sentry/aws-serverless"]:::sdkblue
      Profiling["@sentry/profiling-node"]:::sdkblue
      Types["@sentry/types"]:::utilgreen
    end

    subgraph "dev-packages/"
      DevBrowser["browser-integration-tests"]:::testorange
      DevNode["node-integration-tests"]:::testorange
      DevBundle["bundle-analyzer-scenarios"]:::testorange
      DevClearCache["clear-cache-gh-action"]:::testorange
      DevExternal["external-contributor-gh-action"]:::testorange
      DevSizeLimit["size-limit-gh-action"]:::testorange
    end

    subgraph "CI/CD Pipeline"
      Workflows[".github/workflows"]:::cipurple
      InstallAction["install-dependencies"]:::cipurple
      RestoreCache["restore-cache"]:::cipurple
    end

  end

  %% Dependencies: Core -> SDKs
  Core -->|depends on| Browser
  Core -->|depends on| Node
  Core -->|depends on| React
  Core -->|depends on| Angular
  Core -->|depends on| Nextjs
  Core -->|depends on| Deno
  Core -->|depends on| Bun
  Core -->|depends on| Cloudflare
  Core -->|depends on| AWS
  Core -->|depends on| Profiling
  Core -->|depends on| Types

  %% Utilities -> SDKs
  BrUtils -->|util for| Browser
  BrUtils -->|util for| React
  BrUtils -->|util for| Angular
  Shims -->|shim for| Browser
  Shims -->|shim for| React
  Shims -->|shim for| Angular

  %% Tests consume builds
  Core -->|tested by| DevBrowser
  Browser -->|tested by| DevBrowser
  Node -->|tested by| DevNode

  %% CI/CD flows
  Workflows -->|runs| InstallAction
  Workflows -->|runs| RestoreCache
  InstallAction -->|uses| Scripts
  RestoreCache -->|uses| Scripts
  Workflows -->|"triggers builds on"| Core
  Workflows -->|"triggers builds on"| Browser
  Workflows -->|"triggers builds on"| Node
  Workflows -->|"triggers tests on"| DevBrowser
  Workflows -->|"triggers tests on"| DevNode

  %% Click Events
  click Lerna "https://github.com/getsentry/sentry-javascript/blob/develop/lerna.json"
  click Nx "https://github.com/getsentry/sentry-javascript/blob/develop/nx.json"
  click PkgRoot "https://github.com/getsentry/sentry-javascript/blob/develop/package.json"
  click TsCfg "https://github.com/getsentry/sentry-javascript/blob/develop/tsconfig.json"
  click GitHubCfg "https://github.com/getsentry/sentry-javascript/tree/develop/.github/"
  click DocsRoot "https://github.com/getsentry/sentry-javascript/tree/develop/docs/"
  click Scripts "https://github.com/getsentry/sentry-javascript/tree/develop/scripts/"
  click Core "https://github.com/getsentry/sentry-javascript/blob/develop/packages/core/package.json"
  click Browser "https://github.com/getsentry/sentry-javascript/blob/develop/packages/browser/package.json"
  click Node "https://github.com/getsentry/sentry-javascript/blob/develop/packages/node/package.json"
  click React "https://github.com/getsentry/sentry-javascript/blob/develop/packages/react/package.json"
  click Angular "https://github.com/getsentry/sentry-javascript/blob/develop/packages/angular/package.json"
  click Nextjs "https://github.com/getsentry/sentry-javascript/blob/develop/packages/nextjs/package.json"
  click BrUtils "https://github.com/getsentry/sentry-javascript/blob/develop/packages/browser-utils/package.json"
  click Shims "https://github.com/getsentry/sentry-javascript/blob/develop/packages/integration-shims/package.json"
  click Deno "https://github.com/getsentry/sentry-javascript/blob/develop/packages/deno/package.json"
  click Bun "https://github.com/getsentry/sentry-javascript/blob/develop/packages/bun/package.json"
  click Cloudflare "https://github.com/getsentry/sentry-javascript/blob/develop/packages/cloudflare/package.json"
  click AWS "https://github.com/getsentry/sentry-javascript/blob/develop/packages/aws-serverless/package.json"
  click Profiling "https://github.com/getsentry/sentry-javascript/blob/develop/packages/profiling-node/package.json"
  click Types "https://github.com/getsentry/sentry-javascript/blob/develop/packages/types/package.json"
  click DevBrowser "https://github.com/getsentry/sentry-javascript/tree/develop/dev-packages/browser-integration-tests/"
  click DevNode "https://github.com/getsentry/sentry-javascript/tree/develop/dev-packages/node-integration-tests/src/"
  click DevBundle "https://github.com/getsentry/sentry-javascript/tree/develop/dev-packages/bundle-analyzer-scenarios/"
  click DevClearCache "https://github.com/getsentry/sentry-javascript/blob/develop/dev-packages/clear-cache-gh-action/index.mjs"
  click DevExternal "https://github.com/getsentry/sentry-javascript/blob/develop/dev-packages/external-contributor-gh-action/index.mjs"
  click DevSizeLimit "https://github.com/getsentry/sentry-javascript/blob/develop/dev-packages/size-limit-gh-action/index.mjs"
  click Workflows "https://github.com/getsentry/sentry-javascript/blob/develop/.github/workflows/build.yml"
  click InstallAction "https://github.com/getsentry/sentry-javascript/blob/develop/.github/actions/install-dependencies/action.yml"
  click RestoreCache "https://github.com/getsentry/sentry-javascript/blob/develop/.github/actions/restore-cache/action.yml"

  %% Styles
  classDef sdkblue fill:#D0E8FF,stroke:#4A90E2,color:#042A57;
  classDef coregreen fill:#DFF2D8,stroke:#4CAF50,color:#1B5E20;
  classDef utilgreen fill:#E6F4F1,stroke:#00796B,color:#004D40;
  classDef testorange fill:#FFE8C4,stroke:#FB8C00,color:#E65100;
  classDef cipurple fill:#F3E5F5,stroke:#9C27B0,color:#4A148C;
  classDef config fill:#ECEFF1,stroke:#90A4AE,color:#37474F;
  classDef docgray fill:#F5F5F5,stroke:#B0BEC5,color:#455A64;
```
