@heartbeep/beeper
v0.1.2
Published
Modern JavaScript SDK for Heartbeep event tracking - beep beep!
Maintainers
brandonarbiniReadme
@heartbeep/beeper 🔔
Modern JavaScript SDK for Heartbeep event tracking. Simple API, TypeScript support, React/Next.js ready. Beep beep!
Installation
npm install @heartbeep/beeper
# or
pnpm add @heartbeep/beeper
# or
yarn add @heartbeep/beeperQuick Start
Vanilla JavaScript/TypeScript
import { Heartbeep } from "@heartbeep/beeper";
const heartbeep = new Heartbeep({
siteId: "your-site-id",
debug: true, // optional, logs events in development
});
// Track events
heartbeep.track("pageview");
heartbeep.track("click", { name: "Subscribe Button" });
heartbeep.track("purchase", {
name: "Premium Plan",
metadata: { value: 99.99, currency: "USD" },
});
// Convenience methods
heartbeep.pageview("Home Page");
heartbeep.click("Buy Now Button", { section: "hero" });
heartbeep.purchase("Pro Plan", { value: 49.99 });React
import { HeartbeepProvider, useHeartbeep } from "@heartbeep/beeper/react";
// In your root component
function App() {
return (
<HeartbeepProvider siteId="your-site-id">
<YourApp />
</HeartbeepProvider>
);
}
// In any component
function Button() {
const { click } = useHeartbeep();
return (
<button onClick={() => click("CTA Button", { variant: "primary" })}>
Click Me
</button>
);
}Next.js App Router
For Next.js App Router, create a client component wrapper:
// app/providers.tsx
"use client";
import { HeartbeepProvider, AutoPageview } from "@heartbeep/beeper/react";
export function Providers({ children }: { children: React.ReactNode }) {
return (
<HeartbeepProvider siteId="your-site-id">
<AutoPageview />
{children}
</HeartbeepProvider>
);
}Then use it in your root layout:
// app/layout.tsx
import { Providers } from "./providers";
export default function RootLayout({ children }) {
return (
<html>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}Auto Page Tracking
import { HeartbeepProvider, AutoPageview } from "@heartbeep/beeper/react";
function App() {
return (
<HeartbeepProvider siteId="your-site-id">
<AutoPageview />
<YourApp />
</HeartbeepProvider>
);
}API Reference
Heartbeep Class
Constructor
new Heartbeep(config: HeartbeepConfig)Config Options:
siteId(required): Your Heartbeep site IDapiUrl(optional): Custom API URLdebug(optional): Enable debug logging
Methods
track(event, payload?)
Track a custom event.
heartbeep.track("custom-event", {
name: "Event Name",
metadata: { key: "value" },
});pageview(name?)
Track a page view.
heartbeep.pageview("Home Page");click(name, metadata?)
Track a click event.
heartbeep.click("Buy Now Button", { section: "hero" });purchase(name, metadata?)
Track a purchase event.
heartbeep.purchase("Pro Plan", {
value: 49.99,
currency: "USD",
});React Hook
The useHeartbeep() hook provides access to all tracking methods:
const { track, pageview, click, purchase, heartbeep } = useHeartbeep();TypeScript Support
Full TypeScript support with type definitions included:
import type { HeartbeepConfig, TrackEventPayload } from "@heartbeep/beeper";Migration from Script Tag
Replace your script tag:
<!-- Old -->
<script src="/beep.js" data-site-id="site_123"></script>
<script>
window.hb("click", "Button");
</script>With the npm package:
// New
import { Heartbeep } from "@heartbeep/beeper";
const heartbeep = new Heartbeep({ siteId: "site_123" });
heartbeep.click("Button");Fun Beep Function
For a bit of fun, we also export a beep function:
import { beep } from "@heartbeep/beeper";
beep("click", "Fun Button"); // Logs: [Beeper] 🔔 click: Fun ButtonBrowser Support
- Modern browsers with ES2020 support
- Server-side rendering safe
- Graceful degradation for older browsers
License
MIT
Made with ❤️ by Heartbeep. Beep beep!