Traceway JavaScript SDKs

Official JavaScript / TypeScript client SDKs for Traceway — an open-source error tracking and observability platform. This monorepo holds every Traceway package on npm under the @tracewayapp/* scope.

Traceway is a completely open-source error tracking platform. You can self-host it or use Traceway Cloud.

Packages

Every package below lives in packages/<name>/ and is published as @tracewayapp/<name> on npm. All non-deprecated packages move in lockstep — one version, one release.

Browser & framework SDKs

Package	Version	Description
@tracewayapp/frontend		Browser SDK — window.onerror, unhandledrejection, console logs, fetch / XHR actions, History API navigation, rrweb session replay, gzip transport
@tracewayapp/react		React wrapper — <TracewayProvider>, <TracewayErrorBoundary>, useTraceway() hook
@tracewayapp/vue		Vue 3 plugin + useTraceway() composable
@tracewayapp/svelte		Svelte / SvelteKit context-based setup
@tracewayapp/jquery		jQuery integration — auto-captures $.ajax errors

Mobile

Package	Version	Description
@tracewayapp/react-native		React Native + Expo — ErrorUtils global handler, fetch / XHR actions, console logs, device info attributes. Pure JS, works in Expo Go

Foundation

Package	Version	Description
@tracewayapp/core		Shared types and utilities consumed by every other SDK. Zero runtime dependencies. You probably don't need to install this directly

Tooling

Package	Version	Description
@tracewayapp/sourcemap-upload		CLI for uploading .map files so the dashboard can resolve minified production stack traces

Deprecated

These packages are no longer actively developed. New backend integrations should use OpenTelemetry instead — see the OTel guide. The packages still receive security fixes but are frozen at version 1.0.3.

Package	Replacement
@tracewayapp/backend	Node.js + OTel
@tracewayapp/nestjs	NestJS + OTel

Architecture

                  ┌──────────────────────────────┐
                  │ @tracewayapp/core            │  Types, EventBuffer, parseConnectionString,
                  │ (zero deps)                  │  generateUUID, nowISO, wire-format definitions
                  └──────────────┬───────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
              ▼                  ▼                  ▼
   ┌────────────────────┐ ┌──────────────┐ ┌──────────────────────┐
   │ @tracewayapp/      │ │ /react-native│ │ /sourcemap-upload    │
   │   frontend         │ │  (RN, Expo)  │ │  (CLI tool)          │
   │ (browser, rrweb)   │ │              │ │                      │
   └─────────┬──────────┘ └──────────────┘ └──────────────────────┘
             │
   ┌─────────┴──────────┬─────────┬─────────┬──────────┐
   ▼                    ▼         ▼         ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ /react │ │ /vue   │ │/svelte │ │/jquery │ │ direct │
│        │ │        │ │        │ │        │ │ usage  │
└────────┘ └────────┘ └────────┘ └────────┘ └────────┘

@tracewayapp/core is platform-agnostic. frontend is the browser SDK with rrweb; the framework wrappers (react, vue, svelte, jquery) are thin layers on top. react-native does not depend on frontend — it builds directly on core so the bundle stays free of rrweb, CompressionStream, and other browser-only APIs that don't exist on Hermes / JSC.

Getting started as a user

Pick the package that matches your stack and follow its README:

# Browser
npm install @tracewayapp/frontend

# React (browser)
npm install @tracewayapp/react

# Vue 3
npm install @tracewayapp/vue

# Svelte / SvelteKit
npm install @tracewayapp/svelte

# jQuery
npm install @tracewayapp/jquery

# React Native / Expo
npm install @tracewayapp/react-native

Then generate a connection string on your Traceway dashboard and pass it to init(...) (or the framework's provider equivalent).

Repo layout

js-client/
├── packages/
│   ├── core/              # Foundation — types, utilities, zero deps
│   ├── frontend/          # Browser SDK (rrweb, CompressionStream)
│   │   └── examples/
│   │       └── browser-demo/
│   ├── react/
│   │   └── examples/
│   │       └── react-demo/
│   ├── vue/
│   │   └── examples/
│   │       └── vue-demo/
│   ├── svelte/
│   │   └── examples/
│   │       └── svelte-demo/
│   ├── jquery/
│   ├── react-native/      # RN + Expo — built on @tracewayapp/core only
│   │   └── examples/
│   │       └── expo-demo/
│   ├── sourcemap-upload/  # CLI for uploading .map files
│   ├── backend/           # DEPRECATED — use OTel
│   └── nestjs/            # DEPRECATED — use OTel
├── package.json           # npm workspaces root
├── publish.sh             # Lockstep release of every active @tracewayapp/* package
├── deprecate.sh           # One-shot deprecate + final-version publish for backend/nestjs
├── tsconfig.base.json     # Shared TS config inherited by every package
└── vitest.workspace.ts    # Test discovery — globs packages/*/vitest.config.ts

Development

Requires Node.js ≥ 18 and npm ≥ 9.

Install

npm install

The root package.json declares an npm-workspaces array, so a single install at the repo root provisions every package's dependencies and links them to each other (@tracewayapp/react resolves to packages/react/ automatically).

Build

Build every package via the workspace build script (each runs tsup to emit ESM + CJS + .d.ts):

npm run build

Or build a single package:

npm run build --workspace=@tracewayapp/react-native

Build artifacts land in packages/<name>/dist/. The root has no build output of its own.

Test

Vitest runs across every package via the workspace config. Each package has its own vitest.config.ts that defines a project name (react-native, frontend, etc.):

# Whole repo
npm test

# Watch mode
npm run test:watch

# One package
npm test --workspace=@tracewayapp/react-native

# One project (works from the repo root)
npx vitest run --project frontend

Run an example

Each example is a standalone app with its own package.json (so it can install its own framework deps without polluting the root). Build the workspace first, then run the example:

npm install
npm run build
cd packages/react/examples/react-demo
npm install
npm run dev

The Expo example for React Native has a slightly different invocation — see packages/react-native/examples/expo-demo/README.md.

Publishing

publish.sh is the only sanctioned release path. It bumps every active @tracewayapp/* package to the same version, syncs cross-package dependency references (so @tracewayapp/react's dependencies."@tracewayapp/frontend" always matches the new version), runs the build, and publishes each package to npm in topological order:

./publish.sh
# Prompts for the new semver, confirms, then runs:
#   - bumps every packages/<name>/package.json
#   - rewrites cross-package version references
#   - runs `npm run build`
#   - publishes each package to npm

The script is idempotent — it checks npm whoami first, only re-publishes packages that don't already have the target version, and aborts cleanly if any single package fails (no commit or tag is created on failure; fix the issue and re-run).

For the deprecated backend and nestjs packages, deprecate.sh is a separate one-shot that publishes the final pinned 1.0.3 version with a deprecation notice and npm deprecate's every prior version.

Lockstep versioning

Why every active package shares a single version: the framework wrappers (react, vue, svelte, jquery) all peer-depend on a specific @tracewayapp/frontend version, and react-native peer-depends on a specific @tracewayapp/core version. Bumping any one package without rebuilding the others would create a window where npm install @tracewayapp/react pulls in an incompatible frontend. Lockstep avoids that.

The deprecated backend and nestjs packages are excluded from this rule — they're frozen at 1.0.3 and won't get version bumps anymore.

Links

• Traceway Website
• Documentation
• Main Traceway repo — backend, dashboard, deployment guides
• Flutter SDK — sister repo
• Android SDK — sister repo

License

MIT — see LICENSE.

Finding a user's sessions

Enable always-on recording and optionally supply identity attributes at initialization:

import { init, setAttributes, clearAttributes } from "@tracewayapp/frontend";

init("your-token@https://traceway.example.com/api/report", {
  recordAllSessions: true,
  attributes: { userId: "u_42", email: "alice@example.com" },
});

// When identity becomes available after initialization:
setAttributes({ userId: "u_42", tenant: "acme" });

// On logout, remove app-defined context:
clearAttributes();

Attribute values are strings. setAttribute, setAttributes, removeAttribute, and clearAttributes refresh the current session and affect subsequent exceptions. The React, Vue, Svelte, and jQuery integrations accept the same initialization options. In Traceway's Sessions page, search for a user ID or email, or add an attribute filter such as userId=u_42. Filters appear as editable chips and can be combined.

The attributes initialization option is optional. Existing initialization calls and /api/report payloads without session attributes remain supported.