TraceKit — Local-first error intelligence (prototype)

TraceKit provides a small, local-first developer experience for collecting and inspecting runtime and dev-time errors during app development. It pairs a lightweight SDK (installed into the app under development) with a local companion server and a standalone UI at http://127.0.0.1:4321.

Status: prototype — use for development only.

Overview and key promises

• The SDK must be installed inside the target app to capture runtime JS errors (browser or Node). There is no "magic" remote injection of runtime instrumentation.
• The local server ingests events, groups them, and serves a UI for inspection.
• An optional network monitor component can observe HTTP-level failures (500s, network errors, CORS issues). It cannot see JS runtime stack traces or React errors.

Quickstart — two workflows

1. For app developers (how to use TraceKit with your app):

• Install the SDK into your app (example package layout shown below). -- Start the local TraceKit server + UI (run on your dev machine):

# start the local server & UI (from the TraceKit CLI or local repo)
npx tracekit dev

Open http://127.0.0.1:4321 in your browser to view captured events.

2. For contributors (working on the TraceKit repo itself):

npm install
npm run dev

This runs the codebase locally (ts-node) and serves the same UI at http://127.0.0.1:4321.

Commands (recommended CLI surface)

• npx tracekit dev — start local server + UI
• npx tracekit status — check server health
• npx tracekit network — start the network monitor (HTTP-level diagnostics only)

Important security/behavior notes

• The network monitor is a network-level diagnostic tool only. It cannot capture JS runtime exceptions, stack traces, or application-internal errors. Rename --proxy to --network-monitor if present in the CLI and document this limitation clearly.
• Never promise zero-code setup for runtime error capture. State clearly that runtime capture requires installing the SDK into the running app.

SDK usage (recommended public entry points)

Prefer published, stable entry points instead of reaching into build output paths. Example public APIs we recommend exposing from the package exports:

Browser (recommended install via package manager):

import { installBrowser } from 'tracekit/browser'

installBrowser({ projectId: 'proj_local', environment: 'local' })

Browser (experimental/demo via script tag):

<!-- experimental/demo only -->
<script src="/path/to/browser.js"></script>
<script>
   // experimental: explicitly call install to instrument the page
   TraceKit && TraceKit.install && TraceKit.install({ projectId: 'proj_local' })
</script>

Node / Next.js (dev-time only):

// prefer a stable entry point exported by the package
import { installNode } from 'tracekit/node'

installNode({ projectId: 'proj_local', environment: 'local' })

Do not require('@tracekit/core/dist/...') or import deep paths — this bypasses package exports, breaks bundlers, and is fragile across builds.

Events API (ingest contract)

All ingestion POSTs to /events MUST include a projectId and an environment field so the server can correctly group and isolate events.

Example JSON shape (required fields):

{
   "projectId": "proj_local",
   "environment": "local",
   "event": {
      "id": "evt-123",
      "type": "runtime",
      "message": "Example error",
      "timestamp": 1600000000000,
      "payload": { /* optional error details, stack, metadata */ }
   }
}

Example curl (zsh) — replace timestamp with Date.now() if you like:

curl -X POST http://127.0.0.1:4321/events \
   -H 'Content-Type: application/json' \
   -d '{"projectId":"proj_local","environment":"local","event":{"id":"test-1","type":"runtime","message":"manual test","timestamp":1690000000000}}'

Or from the browser console:

fetch('http://127.0.0.1:4321/events', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({ projectId: 'proj_local', environment: 'local', event: { id: 't-'+Date.now(), type: 'runtime', message: 'hello', timestamp: Date.now() } })
}).then(r => r.json()).then(console.log)

Build & publish

• Build artifacts are emitted to dist/ (when running npm run build).
• Ensure package exports expose stable entrypoints such as ./browser and ./node so integrators can import without deep paths.

Notes

• Prototype uses an in-memory store. Document prominently: "Data is lost on restart" and provide the recommended migration to SQLite or similar for persistence.
• The SDK defaults to posting to http://127.0.0.1:4321 in development; make the target configurable.
• Do not include the SDK in production builds — it is dev-only by design.

Contributing

• File issues or PRs against the repository specified in package.json.

Recommended next steps for the project

• Rename --proxy to --network-monitor and document its limitations.
• Add projectId as a required field in the ingestion schema and validate on the server.
• Add public exports for browser and node entry points and update README examples.
• Make the in-memory store a clearly documented optional prototype and provide a migration guide to a persistent store.