Node SDK

Server-side errors and failing upstream calls, Node 18+.For an Express/Fastify/Next API or any Node process. Zero runtime dependencies.

Install

terminal — bash
npm install @vigil/node

Initialize

server.js — js
import { init, captureError } from '@vigil/node';
init({ key: 'vg_pub_YOUR_KEY', endpoint: 'https://vigill.dev/api/ingest' });
// uncaughtException and unhandledRejection are captured automatically.
try {
  await charge(order);
} catch (err) {
  captureError(err, { tags: { area: 'billing' } });
  throw err;
}

What it captures automatically

These arrive with zero extra code — the unhandled failures that would otherwise crash or vanish.

uncaughtException — an error that would otherwise crash the process.
unhandledRejection — a promise that rejects with no catch.
Failed outgoing fetch() calls to third parties (captureHttp, on by default) — 4xx/5xx and network errors.

When to capture manually

Inside an Express/Fastify route you usually catch errors to return a clean 500 instead of crashing. Once caught, the global handler never fires — call captureError so the handled failure is still reported (and add tags for where it happened).

a route handler — js
app.post('/checkout', async (req, res) => {
  try {
    await charge(req.body);
    res.json({ ok: true });
  } catch (err) {
    captureError(err, { tags: { route: 'checkout' } });
    res.status(500).json({ error: 'Payment failed' });
  }
});

Configuration

Pass environment/release for cleaner grouping; turn off captureHttp if you do not want upstream failures reported.

server.js — js
init({
  key: 'vg_pub_YOUR_KEY',
  endpoint: 'https://vigill.dev/api/ingest',
  environment: 'production',
  release: process.env.GIT_SHA,
  captureHttp: true,      // report third-party 4xx/5xx (default)
  tags: { service: 'api' },
});

What you get

init({ key, endpoint, environment, release, tags, captureHttp, debug })
captureError(error, { message?, tags? }) · captureMessage(message, level)
flush() / close() — force-send anything queued (useful before a short-lived process exits).

Initialize

server.js — js

import { init, captureError } from '@vigil/node'; init({ key: 'vg_pub_YOUR_KEY', endpoint: 'https://vigill.dev/api/ingest' }); // uncaughtException and unhandledRejection are captured automatically. try { await charge(order); } catch (err) { captureError(err, { tags: { area: 'billing' } }); throw err; }

What it captures automatically

These arrive with zero extra code — the unhandled failures that would otherwise crash or vanish.

uncaughtException — an error that would otherwise crash the process.

unhandledRejection — a promise that rejects with no catch.

Failed outgoing fetch() calls to third parties (captureHttp, on by default) — 4xx/5xx and network errors.

When to capture manually

a route handler — js

app.post('/checkout', async (req, res) => { try { await charge(req.body); res.json({ ok: true }); } catch (err) { captureError(err, { tags: { route: 'checkout' } }); res.status(500).json({ error: 'Payment failed' }); } });

Configuration

Pass environment/release for cleaner grouping; turn off captureHttp if you do not want upstream failures reported.

server.js — js

init({ key: 'vg_pub_YOUR_KEY', endpoint: 'https://vigill.dev/api/ingest', environment: 'production', release: process.env.GIT_SHA, captureHttp: true, // report third-party 4xx/5xx (default) tags: { service: 'api' }, });