LAWDE Shield · Documentation

JavaScript / TypeScript

Official isomorphic agent for Node.js, browsers, Express, Fastify, Koa, NestJS, and Next.js. Phase A proves ingest works; Phase B wires the agent into your main app so live crashes keep flowing — still built-in scrubbing in <50ms with 0 bytes durable source.

What does the JavaScript SDK do?

@lawdeshield/agent attaches process/window handlers and posts scrubbed crashes to Sentinel with built-in scrubbing in under 50ms. Athena diagnosis and the 0.70 trust gate run later; the SDK does not upload your repository (0 bytes durable source).

Mode	Purpose
Smoke test script	Prove the API key once
Live boot wire	Catch real production crashes

1. Install the package

Run this inside the repository of the application you want to monitor (not only inside the LAWDE monorepo unless you are developing the agent itself).

npm

npm install @lawdeshield/agent
# If npm reports deprecation/vulnerability warnings from sub-dependencies:
npm audit fix
# Do NOT run: npm audit fix --force

2. Phase A — One-time test crash (optional but recommended)

Create lawde-init.js in the project root, paste the snippet, then run node lawde-init.js. Open Overview and confirm a cluster appears. This file is a smoke test — you can delete it afterward. It does not keep listening for future crashes.

lawde-init.js

// File: lawde-init.js  ← SMOKE TEST ONLY (run once with: node lawde-init.js)
import { LawdeAgent } from '@lawdeshield/agent';

const agent = new LawdeAgent({
  apiKey: process.env.LAWDE_API_KEY!,
  appId: process.env.LAWDE_APP_ID,
});

await agent.captureException(new Error('LAWDE Shield Initial Test Crash'));
console.log('Test crash sent. Now wire the agent into your MAIN app boot (below).');

3. Phase B — Wire into your MAIN app for LIVE crashes

Create a small module (for example src/lawde.ts) that constructs LawdeAgent once — or put the constructor directly in your boot file.
Load that code from whichever entry your stack actually starts (table above).
Restart the process. With default autoInstrument: true, the agent attaches uncaughtException / unhandledRejection (Node) or window listeners (browser).
For framework-handled errors (Express middleware, Nest filters), also register the built-in helper so errors that never become “uncaught” are still reported.

src/lawde.ts

// File: src/lawde.ts  ← LIVE WIRE (imported every time your app starts)
import { LawdeAgent } from '@lawdeshield/agent';

/**
 * Creating LawdeAgent with default options attaches global handlers:
 * - Node.js: process 'uncaughtException' + 'unhandledRejection'
 * - Browser: window 'error' + 'unhandledrejection'
 * LAWDE does not pull crashes — this process must stay running and keep these hooks.
 */
export const lawde = new LawdeAgent({
  apiKey: process.env.LAWDE_API_KEY!,
  appId: process.env.LAWDE_APP_ID, // optional UUID from Apps
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'development',
  // autoInstrument: true  // default — set false only if you capture manually
});

// Optional: call from catch blocks for handled errors
// await lawde.captureException(err);

Express / Node entrypoint

// Top of your REAL entry file (server.js / index.ts / main.ts)
import './src/lawde'; // side-effect: registers live crash hooks
// …then create your HTTP server / app.listen() as usual

4. Express (live)

expressErrorHandler() is a standard 4-arity middleware. It calls captureException then next(err). Register it after your routes so Express routes that next(err) or throw are reported even when they do not crash the whole process.

Express

import express from 'express';
import { lawde } from './src/lawde'; // or new LawdeAgent({ … }) here

const app = express();

app.get('/boom', () => {
  throw new Error('Express route crashed'); // reported by expressErrorHandler
});

// Register AFTER routes (Express 4-arity error middleware)
app.use(lawde.expressErrorHandler());
app.listen(3000);

// Also keep autoInstrument so process-level crashes outside Express are reported.

5. Fastify (live)

Pass agent.fastifyErrorHandler() to app.setErrorHandler. The handler reports the error, then sends a JSON status response if the reply is still open.

Fastify

import Fastify from 'fastify';
import { LawdeAgent } from '@lawdeshield/agent';

const app = Fastify();
const agent = new LawdeAgent({
  apiKey: process.env.LAWDE_API_KEY!,
  appId: process.env.LAWDE_APP_ID,
});

app.setErrorHandler(agent.fastifyErrorHandler());
await app.listen({ port: 3000 });

6. Koa (live)

koaErrorHandler() wraps await next() in try/catch, reports, then rethrows so Koa's default error handling still runs. Register it early.

Koa

import Koa from 'koa';
import { LawdeAgent } from '@lawdeshield/agent';

const app = new Koa();
const agent = new LawdeAgent({
  apiKey: process.env.LAWDE_API_KEY!,
  appId: process.env.LAWDE_APP_ID,
});

// Register early so it wraps downstream middleware
app.use(agent.koaErrorHandler());
app.listen(3000);

7. NestJS (live)

Use LawdeAgentNestFilter as a global exception filter so every Nest-handled exception is reported for the life of the Nest process.

NestJS

import { NestFactory } from '@nestjs/core';
import { LawdeAgent, LawdeAgentNestFilter } from '@lawdeshield/agent';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const agent = new LawdeAgent({
    apiKey: process.env.LAWDE_API_KEY!,
    appId: process.env.LAWDE_APP_ID,
  });
  // Global filter = live wire for Nest exceptions
  app.useGlobalFilters(new LawdeAgentNestFilter(agent));
  await app.listen(3000);
}
bootstrap();

8. Next.js App Router (live) — use instrumentation.ts

In traditional Node servers you edit server.js. In Next.js App Router, Vercel / Next manage the Node lifecycle for you. instrumentation.ts is the official Next boot hook for monitoring tools (same pattern as Sentry / Datadog): put new LawdeAgent(...) inside register() so it runs when the server process starts.

The file itself is not magic — LawdeAgent (with default autoInstrument) attaches process.on('uncaughtException') and unhandledRejection. You only need instrumentation.ts if you are on Next; Express users should ignore this section and use §3–§4 instead.

Keep LAWDE_API_KEY server-side only unless you intentionally accept client-side ingest risk. Copy a ready-made .env from Profile → API Credentials.

Next.js instrumentation.ts

// File: instrumentation.ts (project root — Next.js App Router)
// next.config: ensure instrumentation is enabled for your Next version
import { LawdeAgent } from '@lawdeshield/agent';

export function register() {
  // Runs once when the Next.js server process boots
  if (!process.env.LAWDE_API_KEY) {
    console.warn('[LAWDE] LAWDE_API_KEY missing — live crash capture disabled');
    return;
  }

  const agent = new LawdeAgent({
    apiKey: process.env.LAWDE_API_KEY,
    appId: process.env.LAWDE_APP_ID,
    environment: process.env.NODE_ENV || 'production',
  });

  (globalThis as unknown as { __lawdeAgent?: LawdeAgent }).__lawdeAgent = agent;
}

// In a Route Handler / Server Action catch block (optional manual):
// const agent = (globalThis as any).__lawdeAgent;
// await agent?.captureException(err);

9. Browser / SPA (optional live)

Constructing LawdeAgent in a browser bundle attaches window.onerror / unhandledrejection. Only do this if you accept that the key used in the browser can be extracted by users.

Browser

// Client bundle (only if you intentionally want browser crash reporting)
// Never ship a privileged workspace key to the public internet without understanding the risk.
import { LawdeAgent } from '@lawdeshield/agent';

const agent = new LawdeAgent({
  apiKey: process.env.NEXT_PUBLIC_LAWDE_BROWSER_KEY!, // prefer a restricted key if you ever add one
  appId: process.env.NEXT_PUBLIC_LAWDE_APP_ID,
  environment: 'production',
});
// autoInstrument attaches window.onerror + unhandledrejection

10. Configuration reference

Option	Required	Description
`apiKey`	Yes	Workspace API key (`LAWDE_API_KEY`)
`appId`	No	App UUID (`LAWDE_APP_ID`)
`endpoint`	No	Override ingest URL (defaults to production)
`environment`	No	Defaults to `production`
`scrubRules`	No	Extra client-side scrub regexes
`lawdeignore`	No	`.lawdeignore` contents for Nuclear Abort
`autoInstrument`	No	Default `true` — hooks window/process for LIVE crashes
`debug`	No	Log agent failures to the console

11. Verify live wiring

Deploy or restart the process that imports the agent.
Hit a route that throws (or force an unhandled rejection).
Refresh Overview — you should see a new or updated cluster without re-running lawde-init.js.
Optionally click Diagnose Issue (spends one Athena credit; ingest alone never auto-runs AI).

Next steps

Connect GitHub Beacon so Athena can fetch source context.
Other languages: Python · HTTP / cURL
Credentials: Setup Guide

LAWDE Shield · Documentation

JavaScript / TypeScript

What does the JavaScript SDK do?

Mode	Purpose
Smoke test script	Prove the API key once
Live boot wire	Catch real production crashes

1. Install the package

Run this inside the repository of the application you want to monitor (not only inside the LAWDE monorepo unless you are developing the agent itself).

npm

npm install @lawdeshield/agent
# If npm reports deprecation/vulnerability warnings from sub-dependencies:
npm audit fix
# Do NOT run: npm audit fix --force

2. Phase A — One-time test crash (optional but recommended)

lawde-init.js

// File: lawde-init.js  ← SMOKE TEST ONLY (run once with: node lawde-init.js)
import { LawdeAgent } from '@lawdeshield/agent';

const agent = new LawdeAgent({
  apiKey: process.env.LAWDE_API_KEY!,
  appId: process.env.LAWDE_APP_ID,
});

await agent.captureException(new Error('LAWDE Shield Initial Test Crash'));
console.log('Test crash sent. Now wire the agent into your MAIN app boot (below).');

3. Phase B — Wire into your MAIN app for LIVE crashes

Create a small module (for example src/lawde.ts) that constructs LawdeAgent once — or put the constructor directly in your boot file.
Load that code from whichever entry your stack actually starts (table above).
Restart the process. With default autoInstrument: true, the agent attaches uncaughtException / unhandledRejection (Node) or window listeners (browser).
For framework-handled errors (Express middleware, Nest filters), also register the built-in helper so errors that never become “uncaught” are still reported.

src/lawde.ts

// File: src/lawde.ts  ← LIVE WIRE (imported every time your app starts)
import { LawdeAgent } from '@lawdeshield/agent';

/**
 * Creating LawdeAgent with default options attaches global handlers:
 * - Node.js: process 'uncaughtException' + 'unhandledRejection'
 * - Browser: window 'error' + 'unhandledrejection'
 * LAWDE does not pull crashes — this process must stay running and keep these hooks.
 */
export const lawde = new LawdeAgent({
  apiKey: process.env.LAWDE_API_KEY!,
  appId: process.env.LAWDE_APP_ID, // optional UUID from Apps
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'development',
  // autoInstrument: true  // default — set false only if you capture manually
});

// Optional: call from catch blocks for handled errors
// await lawde.captureException(err);

Express / Node entrypoint

// Top of your REAL entry file (server.js / index.ts / main.ts)
import './src/lawde'; // side-effect: registers live crash hooks
// …then create your HTTP server / app.listen() as usual

4. Express (live)

Express

import express from 'express';
import { lawde } from './src/lawde'; // or new LawdeAgent({ … }) here

const app = express();

app.get('/boom', () => {
  throw new Error('Express route crashed'); // reported by expressErrorHandler
});

// Register AFTER routes (Express 4-arity error middleware)
app.use(lawde.expressErrorHandler());
app.listen(3000);

// Also keep autoInstrument so process-level crashes outside Express are reported.

5. Fastify (live)

Pass agent.fastifyErrorHandler() to app.setErrorHandler. The handler reports the error, then sends a JSON status response if the reply is still open.

Fastify

import Fastify from 'fastify';
import { LawdeAgent } from '@lawdeshield/agent';

const app = Fastify();
const agent = new LawdeAgent({
  apiKey: process.env.LAWDE_API_KEY!,
  appId: process.env.LAWDE_APP_ID,
});

app.setErrorHandler(agent.fastifyErrorHandler());
await app.listen({ port: 3000 });

6. Koa (live)

koaErrorHandler() wraps await next() in try/catch, reports, then rethrows so Koa's default error handling still runs. Register it early.

Koa

import Koa from 'koa';
import { LawdeAgent } from '@lawdeshield/agent';

const app = new Koa();
const agent = new LawdeAgent({
  apiKey: process.env.LAWDE_API_KEY!,
  appId: process.env.LAWDE_APP_ID,
});

// Register early so it wraps downstream middleware
app.use(agent.koaErrorHandler());
app.listen(3000);

7. NestJS (live)

Use LawdeAgentNestFilter as a global exception filter so every Nest-handled exception is reported for the life of the Nest process.

NestJS

import { NestFactory } from '@nestjs/core';
import { LawdeAgent, LawdeAgentNestFilter } from '@lawdeshield/agent';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const agent = new LawdeAgent({
    apiKey: process.env.LAWDE_API_KEY!,
    appId: process.env.LAWDE_APP_ID,
  });
  // Global filter = live wire for Nest exceptions
  app.useGlobalFilters(new LawdeAgentNestFilter(agent));
  await app.listen(3000);
}
bootstrap();

8. Next.js App Router (live) — use instrumentation.ts

Keep LAWDE_API_KEY server-side only unless you intentionally accept client-side ingest risk. Copy a ready-made .env from Profile → API Credentials.

Next.js instrumentation.ts

// File: instrumentation.ts (project root — Next.js App Router)
// next.config: ensure instrumentation is enabled for your Next version
import { LawdeAgent } from '@lawdeshield/agent';

export function register() {
  // Runs once when the Next.js server process boots
  if (!process.env.LAWDE_API_KEY) {
    console.warn('[LAWDE] LAWDE_API_KEY missing — live crash capture disabled');
    return;
  }

  const agent = new LawdeAgent({
    apiKey: process.env.LAWDE_API_KEY,
    appId: process.env.LAWDE_APP_ID,
    environment: process.env.NODE_ENV || 'production',
  });

  (globalThis as unknown as { __lawdeAgent?: LawdeAgent }).__lawdeAgent = agent;
}

// In a Route Handler / Server Action catch block (optional manual):
// const agent = (globalThis as any).__lawdeAgent;
// await agent?.captureException(err);

9. Browser / SPA (optional live)

Constructing LawdeAgent in a browser bundle attaches window.onerror / unhandledrejection. Only do this if you accept that the key used in the browser can be extracted by users.

Browser

// Client bundle (only if you intentionally want browser crash reporting)
// Never ship a privileged workspace key to the public internet without understanding the risk.
import { LawdeAgent } from '@lawdeshield/agent';

const agent = new LawdeAgent({
  apiKey: process.env.NEXT_PUBLIC_LAWDE_BROWSER_KEY!, // prefer a restricted key if you ever add one
  appId: process.env.NEXT_PUBLIC_LAWDE_APP_ID,
  environment: 'production',
});
// autoInstrument attaches window.onerror + unhandledrejection

10. Configuration reference

Option	Required	Description
`apiKey`	Yes	Workspace API key (`LAWDE_API_KEY`)
`appId`	No	App UUID (`LAWDE_APP_ID`)
`endpoint`	No	Override ingest URL (defaults to production)
`environment`	No	Defaults to `production`
`scrubRules`	No	Extra client-side scrub regexes
`lawdeignore`	No	`.lawdeignore` contents for Nuclear Abort
`autoInstrument`	No	Default `true` — hooks window/process for LIVE crashes
`debug`	No	Log agent failures to the console

11. Verify live wiring

Deploy or restart the process that imports the agent.
Hit a route that throws (or force an unhandled rejection).
Refresh Overview — you should see a new or updated cluster without re-running lawde-init.js.
Optionally click Diagnose Issue (spends one Athena credit; ingest alone never auto-runs AI).

Next steps

Connect GitHub Beacon so Athena can fetch source context.
Other languages: Python · HTTP / cURL
Credentials: Setup Guide

What does the JavaScript SDK do?

1. Install the package

2. Phase A — One-time test crash (optional but recommended)

3. Phase B — Wire into your MAIN app for LIVE crashes

4. Express (live)

5. Fastify (live)

6. Koa (live)

7. NestJS (live)

8. Next.js App Router (live) — use instrumentation.ts

9. Browser / SPA (optional live)

10. Configuration reference

11. Verify live wiring

Next steps

Preparing your secure workspace…

What does the JavaScript SDK do?

1. Install the package

2. Phase A — One-time test crash (optional but recommended)

3. Phase B — Wire into your MAIN app for LIVE crashes

4. Express (live)

5. Fastify (live)

6. Koa (live)

7. NestJS (live)

8. Next.js App Router (live) — use instrumentation.ts

9. Browser / SPA (optional live)

10. Configuration reference

11. Verify live wiring

Next steps