npm

Install @faultsense/agent for use with Vite, webpack, esbuild, Rollup, or any bundler.

Install

npm install @faultsense/agent

Initialize

Import init and call it once at your app's entry point:

import { init } from '@faultsense/agent';

const cleanup = init({
  releaseLabel: '2.4.1',
  collectorURL: 'https://collector.example.com/events',
  apiKey: 'fs_secret_...',
});

init() returns a cleanup function. Call it when your app unmounts or during hot-module replacement to remove all listeners and observers.

See configuration for every option.

Why importing doesn't auto-initialize

The default npm entry (@faultsense/agent) is a pure module — importing it does not touch window, document, or DOMContentLoaded. This is intentional:

• SSR safety. Server-side rendering environments (Next.js, Nuxt, SvelteKit, Astro) import your modules at build time in Node. A top-level document.addEventListener would crash.
• Tree-shaking. Bundlers can only eliminate dead code from modules with no side effects. The agent's package.json marks the default entry as side-effect-free.
• Test environments. Importing in a Node-only vitest or Jest suite works without jsdom — useful for type checks and smoke tests.

If you want the script-tag auto-install behavior inside a bundler context, import the auto entry instead. You still need a <script id="fs-agent"> tag in your HTML to provide configuration — the auto entry reads data attributes from it on DOMContentLoaded:

<!-- index.html -->
<script id="fs-agent"
  data-release-label="2.4.1"
  data-collector-url="https://collector.example.com/events"
  data-api-key="fs_secret_..."
  hidden>
</script>

// main.ts — your bundler entry point
import '@faultsense/agent/auto';

The auto import attaches to window.Faultsense, finds the #fs-agent tag, and calls init() with the data attributes — identical to loading the IIFE from a CDN. The tag doesn't load a script (no src), it's just a configuration element.

Test setup (vitest)

// setupTests.ts
import { init } from '@faultsense/agent';
import { consoleCollector } from '@faultsense/console-collector';

let cleanup: (() => void) | undefined;

beforeAll(() => {
  cleanup = init({
    releaseLabel: 'test',
    collectorURL: consoleCollector,
  });
});

afterAll(() => {
  cleanup?.();
});

In vitest.config.ts:

export default defineConfig({
  test: {
    environment: 'jsdom',
    setupFiles: ['./setupTests.ts'],
  },
});

The agent requires a DOM. Use jsdom or happy-dom as the test environment. Importing in a node environment is safe (no crash), but init() requires document and window to exist.

Test setup (Jest)

// jest.setup.ts
import { init } from '@faultsense/agent';
import { consoleCollector } from '@faultsense/console-collector';

let cleanup: (() => void) | undefined;

beforeAll(() => {
  cleanup = init({
    releaseLabel: 'test',
    collectorURL: consoleCollector,
  });
});

afterAll(() => {
  cleanup?.();
});

In jest.config.ts:

export default {
  testEnvironment: 'jsdom',
  setupFilesAfterFramework: ['./jest.setup.ts'],
};

Package exports

The @faultsense/agent package exposes three entry points:

TypeScript types are included for the default and ./auto entries.

Exported API

import { init, registerCleanupHook, version } from '@faultsense/agent';
import type { ApiPayload, Configuration, CollectorFunction } from '@faultsense/agent';

• init(config) — start the agent, returns a cleanup function
• registerCleanupHook(fn) — register a function to run during cleanup (e.g., collector teardown)
• version — the agent version string
• ApiPayload — the assertion result shape collectors receive
• Configuration — the full config object type (includes userCohorts)
• CollectorFunction — the (payload: ApiPayload) => void type

Collectors

The agent needs a collector to receive assertion results. See collectors for how to install and wire up @faultsense/panel-collector or @faultsense/console-collector.