usetraceforge

TraceForge JavaScript SDK for sending errors to your TraceForge backend.

🪄 The 2-Click Installation (Recommended)

The easiest way to install and configure TraceForge in a Next.js or Node.js app is to use our interactive CLI wizard. It will automatically install the SDK and write the configuration code for you!

npx usetraceforge-cli init

That's it! If you prefer to do it manually, read the manual instructions below.

Manual Installation

npm install usetraceforge

Local pack test

cd packages/sdk
npm run build
npm pack

Then in any local app:

npm install /path/to/usetraceforge-0.1.4.tgz

Frontend setup

import TraceForge from "usetraceforge";

TraceForge.init({
  apiKey: "YOUR_PROJECT_API_KEY",
  endpoint: "http://localhost:3001/ingest",
  autoCapture: true,
  environment: "production",
  release: "[email protected]"
});

try {
  throw new Error("Something broke");
} catch (error) {
  TraceForge.captureException(error, {
    payload: { route: "/signup" }
  });
}

Backend setup

import express from "express";
import TraceForge from "usetraceforge";

TraceForge.init({
  apiKey: process.env.TRACEFORGE_API_KEY!,
  endpoint: process.env.TRACEFORGE_INGEST_URL,
  environment: process.env.TRACEFORGE_ENV || "production",
  release: process.env.TRACEFORGE_RELEASE || "[email protected]"
});

const app = express();

app.use((error: unknown, _req, res, _next) => {
  TraceForge.captureException(error, {
    payload: { route: "express-error-handler" }
  }).catch(() => undefined);

  res.status(500).json({ error: "Internal server error" });
});

Environment variables

TRACEFORGE_INGEST_URL=http://localhost:3001/ingest
TRACEFORGE_API_KEY=YOUR_PROJECT_API_KEY
TRACEFORGE_ENV=production
[email protected]

Options

• autoCapture: Listen to window.onerror and window.onunhandledrejection.
• ignoreErrors: Array of strings or regex to skip noisy errors.
• beforeSend: Hook to modify/drop events before sending.
• release: Stable release tag like [email protected] or [email protected].

Publish

cd packages/sdk
npm login
npm run build
npm version patch
npm publish --access public

After publish, consumers can install it with:

npm install usetraceforge