@heronsignal/web
v0.1.0
Published
Typed browser SDK for loading HeronSignal and sending frontend events, logs, and errors.
Maintainers
npm-immortal-userReadme
@heronsignal/web
Typed browser SDK for HeronSignal.
Use this package when you want a clean npm-based frontend integration instead of writing the global snippet by hand.
Install
npm install @heronsignal/webpnpm add @heronsignal/webQuick start
import { initHeronSignal, event, log, captureError } from "@heronsignal/web";
await initHeronSignal({
publicKey: "pk_your_workspace_public_key",
});
event("demo_requested", {
location: "hero",
});
log("warn", "Checkout retry happened", {
area: "checkout",
});
try {
// app code
} catch (error) {
captureError(error instanceof Error ? error : String(error));
}How it works
@heronsignal/web is intentionally lightweight.
It:
- sets
window.heronsignalConfig - creates a safe queue for calls made before the tracker finishes loading
- loads
https://api.heronsignal.com/tracker.js - exposes typed helpers for business events, logs, and errors
The real tracker still comes from HeronSignal. This lets HeronSignal ship tracker fixes centrally without requiring every website to upgrade this npm package immediately.
Next.js App Router example
Create a small client component and render it once in your app layout.
"use client";
import { useEffect } from "react";
import { initHeronSignal } from "@heronsignal/web";
export function HeronSignalProvider() {
useEffect(() => {
void initHeronSignal({
publicKey: process.env.NEXT_PUBLIC_HERONSIGNAL_PUBLIC_KEY!,
});
}, []);
return null;
}export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<HeronSignalProvider />
{children}
</body>
</html>
);
}Business events
Business events are safe, intentional milestones that help HeronSignal understand funnels and business journeys.
import { event } from "@heronsignal/web";
event("signup_started", {
location: "pricing_cta",
plan: "starter",
});
event("signup_completed", {
plan: "starter",
});Do not send passwords, payment details, full names, emails, tokens, or sensitive form values.
Logs
import { log } from "@heronsignal/web";
log("info", "User opened pricing calculator", {
source: "pricing_page",
});
log("warn", "Payment retry shown", {
provider: "stripe",
});Errors
import { captureError } from "@heronsignal/web";
try {
await submitSignup();
} catch (error) {
captureError(error instanceof Error ? error : String(error));
}Configuration
initHeronSignal({
publicKey: "pk_your_workspace_public_key",
apiUrl: "https://api.heronsignal.com",
captureConsole: true,
captureNetworkFailures: true,
captureRuntimeErrors: true,
captureResourceErrors: true,
});Options
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| publicKey | string | required | Workspace public key. |
| apiUrl | string | https://api.heronsignal.com | HeronSignal API origin. |
| scriptUrl | string | ${apiUrl}/tracker.js | Custom tracker URL. Mostly useful for local development. |
| autoLoad | boolean | true | Set to false when you want to load the tracker manually. |
| disabled | boolean | false | Disable tracker loading while keeping code paths safe. |
| captureConsole | boolean | domain setting | Hint for console capture. Domain settings still control final behavior. |
| captureNetworkFailures | boolean | domain setting | Hint for failed request capture. |
| captureRuntimeErrors | boolean | domain setting | Hint for runtime error capture. |
| captureResourceErrors | boolean | domain setting | Hint for broken resource capture. |
Privacy
HeronSignal is designed to collect debugging and experience signals, not sensitive user data.
Avoid sending:
- passwords
- payment/card data
- authentication tokens
- personal form values
- private messages
- raw customer content
Prefer small, non-sensitive payloads such as plan, source, location, cta, experiment, and step.