WatchForge JavaScript SDK (@watchforge/browser)

Browser and Node SDK for WatchForge. One call to register() turns on automatic error reporting—no manual try/catch required for typical crashes.

What this package does not require

• No Material UI (MUI) and no other UI library. If npm install fails with errors about @mui/material or @mui/lab, that conflict comes from your app’s existing dependencies, not from WatchForge. Fix or align MUI versions in your project, or install with:

  npm install @watchforge/browser --legacy-peer-deps

• React is optional. It is only needed if you use the React ErrorBoundary export from @watchforge/browser/react. Plain JavaScript, Vue, Angular, etc. can use the main entry without installing React.

Installation

npm install @watchforge/browser

Quick start (all most apps need)

Call register() once as early as possible (e.g. app entry / main bundle), with your DSN from the WatchForge project settings.

import { register } from '@watchforge/browser';

register({
  dsn: 'https://PUBLIC_KEY@your-host/PROJECT_ID',
  app_env: 'production',  // e.g. development | staging | production
  debug: false,           // true while integrating locally
});

That’s enough for automatic reporting in the browser and Node:

| Where | What gets reported automatically | |--------|----------------------------------| | Browser | Uncaught errors (window.onerror), unhandled promise rejections, plus breadcrumbs (console, clicks, navigation) to give context around failures | | Node | uncaughtException and unhandledRejection |

You do not need to call captureException in normal flows—those global handlers already send errors to WatchForge.

How events reach WatchForge

After register(), the SDK buffers events and sends them to your ingestion endpoint derived from the DSN. Failures are grouped and shown in the WatchForge UI like other SDKs.

Optional: copy files instead of npm

You can copy the src/ folder into your repo and import from your path (same register API).

Advanced (optional APIs)

For manual reporting (handled errors, custom messages, immediate flush), see CONFIGURATION_GUIDE.md in this repository. The main package also exports captureException, captureMessage, and flush if you need them—they are not required for automatic error capture.

Deprecated

init() is deprecated; use register() with a dsn field.

Browser support

Modern browsers with ES modules. For React error boundaries, import from @watchforge/browser/react.