@guardification/sdk

Fail-open, async monitoring for Next.js, React, Vite, Vue, Angular, Express, Hono, SvelteKit, Astro, and Nuxt — health, performance, and passive security signals, reported to your Guardification dashboard in plain English.

• Won't break your app. Every path fails open; if the SDK errors it no-ops.
• Won't slow your app. Events buffer in memory and flush after the response via Next's after(); each flush has a 2s timeout and is sampled under load.
• Report-only. It observes and reports - it never blocks traffic.

Install

npm install @guardification/sdk

Next.js (App Router)

1. Register once — instrumentation.ts

import { register as initGuardification } from "@guardification/sdk";

export function register() {
  initGuardification({ projectKey: process.env.GUARDIFICATION_KEY! });
}

// optional: capture server exceptions
export { onRequestError } from "@guardification/sdk";

2. Wrap your middleware — middleware.ts

import { withMonitor } from "@guardification/sdk";

export default withMonitor((req) => {
  // your existing middleware logic
});

3. Wrap route handlers (optional, for per-route timing)

import { monitorRoute } from "@guardification/sdk";

export const POST = monitorRoute(async (req: Request) => {
  // your handler
});

4. Add your key — .env.local

GUARDIFICATION_KEY=sk_live_your_project_key_here

React (SPA / SSR)

Import from @guardification/sdk/react.

Provider

Wrap your app with <GuardificationProvider> once at the root:

import { GuardificationProvider } from "@guardification/sdk/react";

function App() {
  return (
    <GuardificationProvider config={{ projectKey: import.meta.env.VITE_GUARDIFICATION_KEY }}>
      <Router />
    </GuardificationProvider>
  );
}

Error Boundary

Catch render errors and send them to your dashboard:

import { GuardificationErrorBoundary } from "@guardification/sdk/react";

<GuardificationErrorBoundary fallback={<Oops />}>
  <App />
</GuardificationErrorBoundary>

Hooks

• useRouteMonitor(route) — track page-level timing on mount/unmount.
• useMonitorError() — report errors from event handlers, effects, etc.
• useGuardification() — imperative access to capture() / flush().

import { useRouteMonitor, useMonitorError, useGuardification } from "@guardification/sdk/react";

function ProfilePage() {
  useRouteMonitor("/profile");
  const monitorError = useMonitorError();
  const { flush } = useGuardification();

  const onSubmit = async () => {
    try {
      await saveProfile();
      flush();
    } catch (err) {
      monitorError(err);
    }
  };

  return <ProfileForm onSubmit={onSubmit} />;
}

HOC

import { withRouteMonitor } from "@guardification/sdk/react";

const MonitoredHome = withRouteMonitor(HomePage, "/home");

Vite

Import the plugin from @guardification/sdk/vite. It reports build health, duration, and errors to your Guardification dashboard.

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { guardification } from "@guardification/sdk/vite";

export default defineConfig({
  plugins: [
    react(),
    guardification({ projectKey: process.env.GUARDIFICATION_KEY! }),
  ],
});

The plugin hooks into buildStart, buildEnd, and closeBundle. Every hook fails open — a plugin error will never break your build.

Core API (framework-agnostic)

| Export | Purpose | | --- | --- | | init(config) | Configure the SDK (idempotent). | | register(config) | Call once on boot; configures + emits a heartbeat. | | withMonitor(mw) | Wrap Next.js middleware (request timing/status). | | monitorRoute(handler) | Wrap a route handler. | | onRequestError(err, req?) | Record an exception. | | flush() / capture(event) | Manual escape hatches. |

Config

init({
  projectKey: process.env.GUARDIFICATION_KEY!, // required
  endpoint,    // default: hosted ingest URL
  sampleRate,  // 0–1, default 1
  flushAt,     // batch size, default 20
  timeoutMs,   // per-flush network timeout, default 2000
  detect,      // inline runtime threat detection, default true
  debug,       // console.debug internal activity, default false
});

Runtime threat detection

When detect is enabled (the default), each monitored request is scanned — inline, report-only, and fail-open — for:

• attack signatures (SQL injection, XSS, path traversal, command injection) in the path and query string,
• reconnaissance probes to sensitive paths (/.env, /.git, /wp-admin, …),
• known vulnerability-scanner user-agents,
• missing security response headers (reported once per route).

Matches are sent as security events and surfaced on the dashboard's Security page. Detection never blocks or alters a request — it only reports. Set detect: false to disable it. Aggregate detections that need traffic context (brute-force, volumetric abuse, endpoint enumeration) are computed server-side from the request stream, so they work for every framework adapter.

React API

Import from @guardification/sdk/react.

| Export | Purpose | | --- | --- | | GuardificationProvider | Configures the SDK + emits a heartbeat on mount. | | GuardificationErrorBoundary | Catches render errors, reports them. | | useGuardification() | Imperative capture / flush / isReady. | | useMonitorError() | Returns a function to report errors. | | useRouteMonitor(route) | Tracks mount→unmount duration for a route. | | withRouteMonitor(C, route) | HOC that wraps a component with route timing. |

Vite API

Import from @guardification/sdk/vite.

| Export | Purpose | | --- | --- | | guardification(opts) | Vite plugin factory. |

License

MIT