sentry-javascript Documentation

Official Sentry SDKs for JavaScript

8,713 stars TypeScript TypeScript 1 file · ~4,740 tokens #angular#crash-reporting#ember#error-monitoring#hacktoberfest#javascript#javascript-client#nextjs
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy sentry-javascript on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name sentry-javascript -p 3306:3306 --restart always mysql:8.0
Configured Services & Ports
⚙️ db
image: mysql:8.0
🔌 Ports: 3306:3306
⚙️ redis
image: redis:7
🔌 Ports: 6379:6379
docker-compose.yml
yaml (docker-compose.yml) 
services:
  db:
    image: mysql:8.0
    restart: always
    container_name: e2e-tests-tanstackstart-react-mysql
    # The `mysql` 2.x driver doesn't speak MySQL 8's default
    # `caching_sha2_password` auth, so force the legacy plugin.
    command: ['--default-authentication-plugin=mysql_native_password']
    ports:
      - '3306:3306'
    environment:
      MYSQL_ROOT_PASSWORD: docker
    healthcheck:
      test: ['CMD-SHELL', 'mysqladmin ping -h 127.0.0.1 -uroot -pdocker']
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 10s

  redis:
    image: redis:7
    restart: always
    container_name: e2e-tests-tanstackstart-react-redis
    ports:
      - '6379:6379'
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 5s

File: README.md

Bad software is everywhere, and we're tired of it. Sentry is on a mission to help developers write better software
faster, so we can get back to enjoying technology. If you want to join us
Check out our open positions



Official Sentry SDKs for JavaScript

This is the next line of Sentry JavaScript SDKs, comprised in the @sentry/ namespace. It will provide a more
convenient interface and improved consistency between various JavaScript environments.

Contents

Supported Platforms

For each major JavaScript platform, there is a specific high-level SDK that provides all the tools you need in a single
package. Please refer to the README and instructions of those SDKs for more detailed information:

Version Support Policy

We recognize the importance of continued support for our SDK across different versions.
Our commitment is to provide bug fixes and feature updates for older versions based on community demand and usage.

Installation and Usage

To install a SDK, simply add the high-level package, for example:

sh
npm install --save @sentry/browser
yarn add @sentry/browser

Setup and usage of these SDKs always follows the same principle.

javascript
import * as Sentry from '@sentry/browser';

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

Sentry.captureMessage('Hello, world!');

Other Packages

Besides the high-level SDKs, this repository contains shared packages, helpers and configuration used for SDK
development. If you're thinking about contributing to or creating a JavaScript-based SDK, have a look at the resources
below:

  • @sentry/replay:
    Provides the integration for Session Replay.
  • @sentry/core: The base for all
    JavaScript SDKs with interfaces, type definitions and base classes.

Bug Bounty Program

Our bug bounty program aims to improve the security of our open source projects by encouraging the community to identify
and report potential security vulnerabilities. Your reward will depend on the severity of the identified vulnerability.

Our program is currently running on an invitation basis. If you're interested in participating, please send us an email
to [email protected] and tell us, that you are interested in auditing this repository.

For more details, please have a look at https://sentry.io/security/#vulnerability-disclosure.

Contributors

Thanks to everyone who contributed to the Sentry JavaScript SDK!

File: dev-packages/browser-integration-tests/suites/tracing/trace-lifetime/README.md

Tests in this suite are meant to test the lifetime of a trace in the browser SDK and how different events sent are
connected to a trace. This suite distinguishes the following cases:

  1. pageload - Traces started on the initial pageload as head of trace
  2. pageload-meta - Traces started on the initial pageload as a continuation of the trace on the server (via <meta>
    tags)
  3. navigation - Traces started during navigations on a page
  4. tracing-without-performance - Traces originating from an app configured for "Tracing without Performance".

Tests scenarios should be fairly similar for all three cases but it's important we test all of them.

File: dev-packages/browser-integration-tests/README.md

Integration Tests for Sentry Browser SDK

Integration tests for Sentry's Browser SDK use Playwright internally. These tests are run on
latest stable versions of Chromium, Firefox and Webkit.

Structure

The tests are grouped by their scope such as breadcrumbs or onunhandledrejection. In every group of tests, there are
multiple folders containing test cases with their optional supporting assets.

Each case group has a default HTML skeleton named template.hbs, and also a default initialization script named
init.js , which contains the Sentry.init() call. These defaults are used as fallbacks when a specific template.hbs
or init.js is not defined in a case folder.

subject.js contains the logic that sets up the environment to be tested. It also can be defined locally and as a group
fallback. Unlike template.hbs and init.js, it's not required to be defined for a group, as there may be cases that
does not require a subject.

test.ts is required for each test case, which contains the assertions (and if required the script injection logic).
For every case, any set of init.js, template.hbs and subject.js can be defined locally, and each one of them will
have precedence over the default definitions of the test group.

To test page multi-page navigations, you can specify additional page-*.html (e.g. page-0.html, page-1.html) files.
These will also be compiled and initialized with the same init.js and subject.js files that are applied to
template.hbs/html. Note: page-*.html file lookup does not fall back to the parent directories, meaning that page
files have to be directly in the test.ts directory.

text
suites/
|---- breadcrumbs/
      |---- template.hbs [fallback template for breadcrumb tests]
      |---- init.js [fallback init for breadcrumb tests]
      |---- subject.js [optional fallback subject for breadcrumb tests]
      |---- click_event_tree/
            |---- template.hbs [optional case specific template]
            |---- init.js [optional case specific init]
            |---- subject.js [optional case specific subject]
            |---- test.ts [assertions]
            |---- page-*.html [optional, NO fallback!]

Writing Tests

Helpers

utils/helpers.ts contains helpers that could be used in assertions (test.ts). These helpers define a convenient and
reliable API to interact with Playwright's native API. It's highly recommended to define all common patterns of
Playwright usage in helpers.

Fixtures

Fixtures allows us to define the globals and test-specific information
in assertion groups (test.ts files). In it's current state, fixtures.ts contains an extension over the pure version
of test() function of Playwright. All the tests should import sentryTest function from utils/fixtures.ts instead
of @playwright/test to be able to access the extra fixtures.

Running Tests Locally

Tests can be run locally using the latest version of Chromium with:

yarn test

To run tests with a different browser such as firefox or webkit:

yarn test --project='firefox' yarn test --project='webkit'

Or to run on all three browsers:

yarn test:all

To filter tests by their title:

yarn test -g "XMLHttpRequest without any handlers set"

You can refer to Playwright documentation for other CLI options.

You can set env variable PW_BUNDLE to set specific build or bundle to test against. Available options include: esm, cjs,
bundle, bundle_min, bundle_tracing, bundle_tracing_logs_metrics, bundle_replay, bundle_tracing_replay_feedback, and more.
See package.json scripts for the full list of test:bundle:* commands.

Troubleshooting

Apart from Playwright-specific issues, below are common issues that might
occur while writing tests for Sentry Browser SDK.

  • Flaky Tests

    If a test fails randomly, giving a Page Closed, Target Closed or a similar error, most of the times, the reason is
    a race condition between the page action defined in the subject and the listeners of the Sentry event / request.
    It's recommended to firstly check utils/helpers.ts whether if that async logic can be replaced by one of the
    helpers. If not, whether the awaited (or non-awaited on purpose in some cases) Playwright methods can be orchestrated
    by Promise.all. Manually-defined waiting logic such as timeouts are not recommended,
    and should not be required in most of the cases.

  • Build Errors

    Before running, a page for each test case is built under the case folder inside dist. If a page build is failed,
    it's recommended to check:

    • If both default template.hbs and init.js are defined for the test group.
    • If a subject.js is defined for the test case.
    • If either of init.js or subject.js contain non-browser code.
    • If the webpack configuration is valid.

  • Debugging Tests

    To debug one or multiple test scenarios, you can use playwright's UI mode. This opens a simulated browser window with
    console logs, a timeline of the page and how it was rendered, a list of steps within the test and filtering
    capabilities to run the specific test. This is really helpful to understand what happened during the test or for
    example when a timeout occurred.

    To use UI mode, simply call yarn test --ui and filter on the test in the UI.

    Note: passing the -g flag along with the --ui command doesn't give you an advantage as
    you have to filter on the test again in the UI.

File: dev-packages/e2e-tests/test-applications/vue-tanstack-router/README.md

Vue TanStack Router E2E Test App

E2E test application for @sentry/vue with TanStack Router integration.

Getting Started

To run this application:

bash
pnpm install
pnpm dev

Building For Production

To build this application for production:

bash
pnpm build

Running Tests

To run E2E tests:

bash
pnpm test:build  # Install deps and build
pnpm test:assert # Run Playwright tests

Routing

This project uses TanStack Router for Vue.js. The router is set up with code-based routing in the ./src/main.ts file.

Routes

  • / - Home page with navigation links
  • /posts/$postId - Post detail page with parameterized route

Sentry Integration

The app demonstrates:

  • TanStack Router browser tracing integration
  • Pageload transaction tracking with parameterized routes
  • Navigation transaction tracking
  • Route parameter extraction and span attribution

Testing

The E2E tests verify:

  1. Pageload transactions are created with correct route parameters
  2. Navigation transactions are properly instrumented
  3. Route parameters are captured in transaction data
  4. Sentry origins are correctly set for Vue TanStack Router

Learn More

File: dev-packages/e2e-tests/test-applications/sveltekit-cloudflare-pages/README.md

sv

Everything you need to build a Svelte project, powered by sv.

Creating a project

If you're seeing this, you've probably already done this step. Congrats!

bash
# create a new project in the current directory
npx sv create

# create a new project in my-app
npx sv create my-app

Developing

Once you've created a project and installed dependencies with npm install (or pnpm install or yarn), start a development server:

bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

Building

To create a production version of your app:

bash
npm run build

You can preview the production build with npm run preview.

To deploy your app, you may need to install an adapter for your target environment.

File: dev-packages/e2e-tests/test-applications/sveltekit-2-svelte-5/README.md

create-svelte

Everything you need to build a Svelte project, powered by
create-svelte.

Creating a project

If you're seeing this, you've probably already done this step. Congrats!

bash
# create a new project in the current directory
npm create svelte@latest

# create a new project in my-app
npm create svelte@latest my-app

Developing

Once you've created a project and installed dependencies with npm install (or pnpm install or yarn), start a
development server:

bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

Building

To create a production version of your app:

bash
npm run build

You can preview the production build with npm run preview.

To deploy your app, you may need to install an adapter for your target
environment.

File: dev-packages/e2e-tests/test-applications/sveltekit-2-kit-tracing/README.md

create-svelte

Everything you need to build a Svelte project, powered by
create-svelte.

Creating a project

If you're seeing this, you've probably already done this step. Congrats!

bash
# create a new project in the current directory
npm create svelte@latest

# create a new project in my-app
npm create svelte@latest my-app

Developing

Once you've created a project and installed dependencies with npm install (or pnpm install or yarn), start a
development server:

bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

Building

To create a production version of your app:

bash
npm run build

You can preview the production build with npm run preview.

To deploy your app, you may need to install an adapter for your target
environment.

File: dev-packages/e2e-tests/test-applications/sveltekit-2/README.md

create-svelte

Everything you need to build a Svelte project, powered by
create-svelte.

Creating a project

If you're seeing this, you've probably already done this step. Congrats!

bash
# create a new project in the current directory
npm create svelte@latest

# create a new project in my-app
npm create svelte@latest my-app

Developing

Once you've created a project and installed dependencies with npm install (or pnpm install or yarn), start a
development server:

bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

Building

To create a production version of your app:

bash
npm run build

You can preview the production build with npm run preview.

To deploy your app, you may need to install an adapter for your target
environment.

File: dev-packages/e2e-tests/test-applications/sveltekit-2.5.0-twp/README.md

Tracing Without Performance E2E test app

E2E test app for testing Tracing Without Performance in a (SvelteKit) meta framework scenario

Add tests to this app that specifically test TwP in meta frameworks.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#angular Browse angular catalog → #crash-reporting Browse crash-reporting catalog → #ember Browse ember catalog → #error-monitoring Browse error-monitoring catalog → #hacktoberfest Browse hacktoberfest catalog → #javascript Browse javascript catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →