Set up TraceForge in your app

Install & initialize

One package, zero runtime dependencies. Create a project in the dashboard to get a DSN — it can only send events, so it's safe to ship in frontend code.

npm install @traceforge/sdk

// instrumentation-client.ts (Next.js) or your app's entry point
import { init } from "@traceforge/sdk"

init({
  dsn: process.env.NEXT_PUBLIC_TRACEFORGE_DSN!,
  environment: "production",
})

In Next.js, initialize inside instrumentation-client.ts so monitoring starts before hydration. For any other app, call init() as early as possible in your entry point.

React error boundary

@traceforge/sdk/react catches render errors that never reach window.onerror. react is an optional peer dependency — nothing here is pulled into the core bundle if you don't import it.

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

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

Reports 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 your own handling — a toast, for example.

Next.js server-side errors

@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.

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

export const onRequestError = withTraceForge({
  dsn: process.env.NEXT_PUBLIC_TRACEFORGE_DSN!,
  environment: "production",
})

Reports 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.

Configuration

Every option is optional beyond dsn. Sensible defaults favor privacy and low overhead.

init({
  dsn: process.env.NEXT_PUBLIC_TRACEFORGE_DSN!,
  environment: "production",
  release: process.env.NEXT_PUBLIC_COMMIT_SHA,

  // Monitor a fraction of sessions. Default: 1.
  sampleRate: 0.5,

  // Drop noisy or third-party errors before they're even queued.
  ignoreErrors: ["ResizeObserver loop", /^Network request failed/],

  // Static tags attached to every event.
  tags: { team: "checkout" },

  // A random, non-personal id so the dashboard can count affected users.
  privacy: { captureUserContext: true },

  // Last chance to redact or drop (return null) an event.
  beforeSend(event) {
    return event
  },
})

Alerts & webhooks

Get notified the moment something breaks, without watching a dashboard. Open a project's Settings → Alerts, add a webhook URL — a Slack incoming webhook or any HTTPS endpoint — and choose what should trigger it: new issues, regressions (a resolved issue coming back), or both. TraceForge sends a test payload on save so you can confirm delivery before relying on it.

Releases

Pass a release (your git SHA or a semver string) to init() or withTraceForge(), then tag the same string under Releases in the dashboard. The release page shows events, issues and affected users scoped to that exact deploy — useful for confirming a fix actually shipped, or spotting a regression right after a release goes out.

Self-hosting

TraceForge is MIT licensed and designed to run on free tiers: the dashboard and demo on Vercel, the API on Render, Postgres on Neon. The full walkthrough, including environment variables and troubleshooting, is in docs/DEPLOY.md on GitHub.