@getvigilia/server

Errors from your app's backend, explained by Vigilia in plain language, with a fix prompt for your AI (Lovable, Bolt, Cursor, Claude Code…). Vigilia then checks that the fix held.

• Errors only. No tracing, no logs, no auto-instrumentation.
• Zero dependencies, one small file. It needs only fetch, so it runs on Supabase Edge Functions, Deno, Next.js, Vercel (serverless and edge), Cloudflare Workers, Netlify, Bun and Node 18+.
• Never in the way. It never throws into your code, never touches a response that succeeded, and scrubs emails, tokens, card numbers and bank account numbers (IBANs) before anything leaves your server.

Server errors are part of Vigilia Pro.

Setup

1. In Vigilia, open your app and create a server key under "Server errors".

2. Set two secrets where your backend runs:

   VIGILIA_SERVER_KEY=vgk_…
   VIGILIA_ENDPOINT=https://…/v1/server/events

   Both are shown on the same page. On Supabase, run supabase secrets set VIGILIA_SERVER_KEY=… VIGILIA_ENDPOINT=…. On Cloudflare, add them as secrets (they arrive in env, which Vigilia reads).

3. Wrap your handlers.

Supabase Edge Functions and Deno

import { withVigilia } from 'npm:@getvigilia/server';

Deno.serve(withVigilia(async (req) => {
  // …your function
}, { route: 'checkout' }));

Next.js route handlers and Vercel functions

import { withVigilia } from '@getvigilia/server';

export const POST = withVigilia(async (request: Request) => {
  // …
});

Cloudflare Workers

import { withVigilia } from '@getvigilia/server';

export default withVigilia({
  async fetch(request, env, ctx) {
    // …
  },
});

Errors are sent with ctx.waitUntil, after your response.

Express

import { vigiliaErrorHandler } from '@getvigilia/server';

// after your routes:
app.use(vigiliaErrorHandler());

Errors you catch yourself

A wrapped handler reports anything it throws, and any 5xx it returns, with the error text from a JSON body like { "error": "…" }. For an error you catch and handle some other way:

import { captureException } from '@getvigilia/server';

try {
  await chargeCard();
} catch (error) {
  await captureException(error, { request: req, route: 'checkout' });
  // …your handling
}

AI calls

If your backend calls an AI API, add one line at the top of the file:

import { watchAI } from '@getvigilia/server';

watchAI();

A call that fails is sent to Vigilia, which explains it in plain words: an account out of credit, a rejected key, rate limits, an overloaded provider. That works for OpenAI, Anthropic, Google Gemini, OpenRouter, Lovable AI, Groq, Mistral, DeepSeek and xAI. Running out of credit is the most common cause of an AI feature silently dying, and it's fixed in a billing page, not in code.

It also counts calls and tokens per model, sent in batches rather than one request per call. Vigilia charts them on your app's page and tells you when a day runs to three times your usual: a loop, or an endpoint someone else found, costs money before anything looks broken.

watchAI() wraps fetch and looks only at requests to those providers. Every response is handed back untouched. Calls made by an SDK that brings its own HTTP client, instead of fetch, aren't seen.

Check it works

import { sendTestError } from '@getvigilia/server';

console.log(await sendTestError()); // { ok: true }

It shows up in Vigilia as a test, with nothing to fix. If it says { ok: false, reason }, the reason says what's missing.

Options

Optional; the environment variables above are enough.

import { init } from '@getvigilia/server';

init({
  key: 'vgk_…',          // default: VIGILIA_SERVER_KEY
  endpoint: 'https://…', // default: VIGILIA_ENDPOINT
  environment: 'production', // default: from VERCEL_ENV, Netlify's CONTEXT, NODE_ENV…
  release: 'abc123',     // default: the platform's commit variable
  debug: true,           // log why an error wasn't sent
  beforeSend: (event) => event, // change or drop (return null) an error
});

Errors from preview and development are recorded but never alerted, like errors from your laptop in the browser.

MIT licence.