@emit-vision/sdk-node

Node.js SDK for Emit Vision, the self-hostable analytics and error tracking stack in this repo.

For a full local-first walkthrough, see docs/sdk-node-guide.md.

Installation

npm install @emit-vision/sdk-node

Quick Start

import { captureError, captureEvent, flush, init } from "@emit-vision/sdk-node";

async function main() {
  init({
    dsn: "http://evk_local_development_seed_key_000000000000@localhost:4301/v1",
    environment: "development",
    release: "[email protected]",
  });

  captureEvent("worker_started", { queue: "emails" });
  captureError(new Error("worker failed"), {
    context: { queue: "emails", jobId: "job_123" },
  });

  await flush();
}

void main();

Identifying Users

import { identify } from "@emit-vision/sdk-node";

identify("user_123", {
  email: "[email protected]",
  username: "local-dev",
});

Request Context

Use setContext() for server-wide context and the middleware package for per-request HTTP context.

import { setContext, setTags } from "@emit-vision/sdk-node";

setContext({ worker: "email-delivery", region: "us-west" });
setTags({ release: "[email protected]", queue: "emails" });

Process Hooks

Use installProcessHandlers() when you want the SDK to capture unhandled exceptions and rejections automatically.

import { installProcessHandlers, flush } from "@emit-vision/sdk-node";

installProcessHandlers();

process.on("SIGTERM", () => {
  void flush().finally(() => process.exit(0));
});

Capturing Exceptions

captureException() is a convenience alias for captureError() that also picks up process.domain context when it is available.

import { captureException } from "@emit-vision/sdk-node";

try {
  doSomethingRisky();
} catch (error) {
  captureException(error instanceof Error ? error : new Error("job failed"));
}

Express

import express from "express";
import {
  emitVisionExpress,
  emitVisionRequestContext,
  init,
} from "@emit-vision/sdk-node";

init({
  apiKey: "evk_local_development_seed_key_000000000000",
  endpoint: "http://localhost:4301",
});

const app = express();
app.use(emitVisionRequestContext());

app.get("/checkout", async () => {
  throw new Error("checkout failed");
});

app.use(emitVisionExpress());

Fastify

import Fastify from "fastify";
import { emitVisionFastifyPlugin, init } from "@emit-vision/sdk-node";

init({
  apiKey: "evk_local_development_seed_key_000000000000",
  endpoint: "http://localhost:4301",
});

const app = Fastify();
await app.register(emitVisionFastifyPlugin);

Shutdown

Use the middleware when you want request-scoped HTTP context and framework-specific error capture. Use installProcessHandlers() when you want process-level crash and rejection capture.

Notes

• captureException() captures process.domain context when it is available.
• installProcessHandlers() wires process.on("uncaughtException", ...) and process.on("unhandledRejection", ...).
• Call flush() during shutdown, for example from a process.on("SIGTERM", ...) handler, so queued events are delivered before exit.
• The queue is in-process only, so each worker keeps its own buffer.
• The Node SDK uses the same ingest envelope format as @emit-vision/sdk-js, so the server accepts browser and Node events without a separate API path.
• sessionId is optional and should only be set when your server process has a meaningful session concept.
• The Node SDK does not auto-capture browser window events such as window.error or unhandledrejection.