@nilguard/react

Thin React bindings over @nilguard/browser-sdk: a provider that owns the SDK lifecycle, a hook to reach the client, and an error boundary that reports render-phase crashes (which React otherwise swallows).

npm install @nilguard/react @nilguard/browser-sdk

react and react-dom (>=18) are peer dependencies.

Usage

Wrap your app once. The provider initializes the SDK on mount and keeps the metadata in sync — pass changing userHash/featureFlags/etc. and they are applied via setMetadata without re-initializing.

import { NilguardProvider, NilguardErrorBoundary } from "@nilguard/react";

function Root({ user }: { user?: string }) {
	return (
		<NilguardProvider
			options={{
				siteToken: import.meta.env.VITE_NILGUARD_SITE_TOKEN,
				appId: "my-app",
				environment: "production",
				release: __GIT_SHA__,
				userHash: user,
				replay: { mode: "buffered" },
				console: { mode: "warn-and-error" },
				network: { mode: "metadata" },
				sessionEnd: { mode: "full" },
			}}
		>
			<NilguardErrorBoundary fallback={(err) => <Crashed error={err} />}>
				<App />
			</NilguardErrorBoundary>
		</NilguardProvider>
	);
}

Unhandled window.error / unhandledrejection are captured automatically by the browser SDK. The error boundary covers the gap React leaves: it reports render-phase errors through the client (or re-throws to the global listener if no provider is mounted).

Manual capture

import { useNilguard } from "@nilguard/react";

function PayButton() {
	const nilguard = useNilguard();
	return (
		<button
			onClick={() => {
				try {
					pay();
				} catch (err) {
					nilguard?.reportError(err, { flow: "checkout" });
				}
			}}
		>
			Pay
		</button>
	);
}

useNilguard() returns the NilguardClient (reportError, markCrash, setMetadata, stop) or null before init / outside a provider.

API

• NilguardProvider({ options, children }) — options is the browser SDK's NilguardOptions.
• useNilguard(): NilguardClient | null
• NilguardErrorBoundary({ children, fallback?, onError? }) — fallback may be a node or (error) => node.
• init and all browser-SDK types are re-exported for convenience.