# @traceforge/sdk

> Lightweight browser SDK for TraceForge: JS errors, API failures, Web Vitals and navigation — batched, retried and privacy-first.

Latest version **0.2.0** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @traceforge/sdk
pnpm add @traceforge/sdk
yarn add @traceforge/sdk
bun add @traceforge/sdk
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2026-09-24 |
| First published | 2026-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Huzaif S |
| Maintainers | huzaif_shaikh |
| Keywords | observability, monitoring, error-tracking, web-vitals, rum, performance, react, nextjs |

## Links

- npm: https://www.npmjs.com/package/@traceforge/sdk
- Repository: https://github.com/huzaifsk/TraceForge
- Homepage: https://github.com/huzaifsk/TraceForge#readme
- Issues: https://github.com/huzaifsk/TraceForge/issues
- npm.io page: https://npm.io/package/@traceforge/sdk

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.2.0 (latest) — 2026-09-24
- 0.1.0 — 2026-09-23

## README

# @traceforge/sdk

Lightweight, privacy-first browser monitoring for [TraceForge](https://github.com/huzaifsk/TraceForge):
JavaScript errors, unhandled rejections, API failures, Core Web Vitals and navigation.

> **Pre-release.** Not yet published to npm; build and pack it locally (see the [root README](../../README.md#quick-start)).

```bash
npm install @traceforge/sdk
```

```ts
import { init } from "@traceforge/sdk"

init({
  dsn: "https://<publicKey>@traceforge.example.com/project/<projectId>",
  environment: "production",
})
```

- Zero runtime dependencies. ESM, CommonJS and a CDN build (`window.TraceForge`).
- Never throws into your app: invalid configuration logs one warning and disables monitoring.
- Privacy by default: no input values, cookies, headers or bodies; query-string values are redacted.

## React

`@traceforge/sdk/react` catches render errors `window.onerror` never sees. `react` is an
optional peer dependency — nothing here is pulled into the core bundle.

```tsx
import { TraceForgeErrorBoundary } from "@traceforge/sdk/react"

;<TraceForgeErrorBoundary fallback={<p>Something went wrong.</p>}>
  <App />
</TraceForgeErrorBoundary>
```

Reports the error with `mechanism: "error-boundary"` and the React component stack. `fallback`
can also be a function of `(error, reset)`, and `onError(error, componentStack)` fires alongside
the report for host-side handling (a toast, for example).

## Next.js

`@traceforge/sdk/next` reports crashes in Server Components, Route Handlers and Server Actions —
errors the browser SDK never sees. It's server-only and adds nothing to the browser bundle.

```ts
// instrumentation.ts (project root, not instrumentation-client.ts)
import { withTraceForge } from "@traceforge/sdk/next"

export const onRequestError = withTraceForge({
  dsn: "https://<publicKey>@traceforge.example.com/project/<projectId>",
  environment: "production",
})
```

Reports the error with `mechanism: "server"` and the route template Next.js provides (e.g.
`/orders/[id]`), reusing the same issue grouping, alerts and resolution workflow as browser errors.

MIT licensed.

---
_Source: https://npm.io/package/@traceforge/sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._