@heartbeep/beeper 🔔

Modern JavaScript SDK for Heartbeep event tracking. Simple API, TypeScript support, React/Next.js ready. Beep beep!

Installation

``bash
npm install @heartbeep/beeper


or

pnpm add @heartbeep/beeper

or

yarn add @heartbeep/beeper
`

Quick Start

$3

`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 });
`

$3

`tsx
import { HeartbeepProvider, useHeartbeep } from "@heartbeep/beeper/react";

// In your root component
function App() {
return (



);
}

// In any component
function Button() {
const { click } = useHeartbeep();

return (
click("CTA Button", { variant: "primary" })}>
Click Me

);
}
`

$3

For Next.js App Router, create a client component wrapper:

`tsx
// app/providers.tsx
"use client";

import { HeartbeepProvider, AutoPageview } from "@heartbeep/beeper/react";

export function Providers({ children }: { children: React.ReactNode }) {
return (


{children}

);
}
`

Then use it in your root layout:

`tsx
// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }) {
return (


{children}


);
}
`

$3

`tsx
import { HeartbeepProvider, AutoPageview } from "@heartbeep/beeper/react";

function App() {
return (




);
}
`

API Reference

$3

#### Constructor

`typescript
new Heartbeep(config: HeartbeepConfig)
`

Config Options:

- siteId (required): Your Heartbeep site ID
- apiUrl (optional): Custom API URL
- debug (optional): Enable debug logging

#### Methods

##### track(event, payload?)

Track a custom event.

`typescript
heartbeep.track("custom-event", {
name: "Event Name",
metadata: { key: "value" },
});
`

##### pageview(name?)

Track a page view.

`typescript
heartbeep.pageview("Home Page");
`

##### click(name, metadata?)

Track a click event.

`typescript
heartbeep.click("Buy Now Button", { section: "hero" });
`

##### purchase(name, metadata?)

Track a purchase event.

`typescript
heartbeep.purchase("Pro Plan", {
value: 49.99,
currency: "USD",
});
`

$3

The useHeartbeep() hook provides access to all tracking methods:

`typescript
const { track, pageview, click, purchase, heartbeep } = useHeartbeep();
`

TypeScript Support

Full TypeScript support with type definitions included:

`typescript
import type { HeartbeepConfig, TrackEventPayload } from "@heartbeep/beeper";
`

Migration from Script Tag

Replace your script tag:

`html



`

With the npm package:

`typescript
// 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:

`typescript
import { beep } from "@heartbeep/beeper";

beep("click", "Fun Button"); // Logs: [Beeper] 🔔 click: Fun Button
``

Browser Support

- Modern browsers with ES2020 support
- Server-side rendering safe
- Graceful degradation for older browsers

License

MIT

---

Made with ❤️ by Heartbeep. Beep beep!