JS SDK Overview
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
| Package | Description |
|---|---|
@tracewayapp/frontend | Core browser SDK (framework-agnostic) |
@tracewayapp/react | React bindings with Provider, Error Boundary, and hooks |
@tracewayapp/vue | Vue 3 plugin and composables |
@tracewayapp/svelte | Svelte context-based integration |
@tracewayapp/jquery | jQuery integration with automatic AJAX error capture |
Installation
npm install @tracewayapp/frontendOr 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/jqueryVia 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/reportExample:
abc123def456@https://traceway.example.com/api/reportYou 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.persistthey 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
fetchandXMLHttpRequestcalls as spans and sends the W3Ctraceparentheader, 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)