JS SDK Reference
Overview

JS SDK Overview

This page documents the 2.x browser SDK. Still on 1.x? See the 1.x version of this page, or follow the migration guide to upgrade.

This reference covers the 2.x browser SDK and its framework wrappers. It uses OpenTelemetry and supports remote collection settings. Version 2.0.0 is the current release on npm, so a plain npm install gets it. Coming from 1.x? Follow Migrating from 1.x to 2.x.

The Traceway JavaScript SDK is the browser side of Real User Monitoring. It captures exceptions and messages, measures web vitals, route changes and requests as performance metrics, reports sessions, and keeps breadcrumbs and session replay on the device until an error, a trigger or a capture asks for them.

Packages

PackageDescription
@tracewayapp/frontendCore browser SDK (framework-agnostic)
@tracewayapp/reactReact bindings with Provider, Error Boundary, and hooks
@tracewayapp/vueVue 3 plugin and composables
@tracewayapp/svelteSvelte context-based integration
@tracewayapp/jqueryjQuery integration with automatic AJAX error capture

Installation

npm install @tracewayapp/frontend

Or use a framework-specific package. It installs the matching @tracewayapp/frontend for you:

npm install @tracewayapp/react
npm install @tracewayapp/vue
npm install @tracewayapp/svelte
npm install @tracewayapp/jquery

Via CDN

The frontend and jQuery packages are also available as standalone scripts (no bundler required):

<!-- Framework-agnostic (exposes window.Traceway) -->
<script src="https://cdn.jsdelivr.net/npm/@tracewayapp/frontend@2/dist/traceway.iife.global.js"></script>
<script>
  Traceway.init("your-token@https://traceway.example.com/api/report");
</script>
<!-- jQuery (exposes window.TracewayJQuery) -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@tracewayapp/jquery@2/dist/traceway-jquery.iife.global.js"></script>
<script>
  TracewayJQuery.init("your-token@https://traceway.example.com/api/report");
</script>

Connection String Format

All Traceway SDKs use a connection string to identify your project and endpoint:

<project_token>@<server_url>/api/report

Example:

abc123def456@https://traceway.example.com/api/report

You can find your connection string on the project’s Connection page.

When to Use

Use the generic @tracewayapp/frontend package when:

  • You're using a framework without official bindings
  • You need direct control over initialization
  • You're building a vanilla JavaScript application
  • You want to integrate with a custom framework

For React, Vue, or Svelte applications, use the framework-specific packages for better integration and developer experience.

Basic Usage

import { init, captureException, captureMessage } from "@tracewayapp/frontend";
 
// Initialize once at app startup
init("your-token@https://traceway.example.com/api/report");
 
// Capture errors
try {
  riskyOperation();
} catch (error) {
  captureException(error);
}
 
// Capture custom messages
captureMessage("User completed checkout");

Features

  • Automatic batching: Logs and spans go out in OTLP batches, by default about a second apart (exportDelayMs)
  • Automatic retry: Batches that fail with a retryable status (such as 429 or 503) are retried with backoff; with buffer.persist they also survive page loads (see Flush & Lifecycle)
  • Stack trace capture: Full stack traces are captured for exceptions
  • Custom attributes: Attach metadata to exceptions for better debugging
  • Distributed tracing: Records fetch and XMLHttpRequest calls as spans and sends the W3C traceparent header, so a browser request and the backend work it caused share one trace. This covers $.ajax() and browser Axios with no extra setup (see Distributed Tracing)
  • Session replay and breadcrumbs: kept on the device and uploaded with an error, a trigger or a capture (see Session Replay)
  • Remote collection settings: change what browsers send from the Data Collection page, without a release (see Remote SDK Config)