Getting Started

Quick installation and setup guide to get Honolytics running in your React application.

Ready to integrate Honolytics into your React app? Let's get you set up in minutes.

Installation

bun add honolytics

Quick Start

HTTP Mode (v0.1 compatibility)

Connect to your existing analytics API:

Generate API Key

Create a secure key for your application

import { HonolyticsProvider } from 'honolytics'

export default function App() {
  return (
    <HonolyticsProvider
      apiKey={process.env.NEXT_PUBLIC_ANALYTICS_KEY!}
      endpoint={process.env.NEXT_PUBLIC_ANALYTICS_URL!}
    >
      <YourApp/> || {children}
    </HonolyticsProvider>
  )
}

Storage Mode (v0.2.0)

Use built-in storage instead of HTTP requests:

import { HonolyticsProvider } from 'honolytics'
import { initStorage, postgres } from 'honolytics/storage'

// Initialize storage once
await initStorage(postgres({ url: 'postgresql://...' }))

export default function App() {
  return (
    <HonolyticsProvider storageMode={true}>
      <YourApp />
    </HonolyticsProvider>
  )
}

Usage

Same hooks for both modes:

import { useAnalytics, useTotals } from 'honolytics'

function Dashboard() {
  const { data, loading, error } = useAnalytics()
  const { data: totals } = useTotals()
  
  return (
    <div>
      <h1>Analytics Dashboard</h1>
      {data && (
        <>
          <div>Users: {data.totals.users}</div>
          <div>Pageviews: {data.totals.pageviews}</div>
          <div>Top Pages: {data.breakdowns.topPages.length}</div>
        </>
      )}
    </div>
  )
}

Next Steps

Now that you have Honolytics installed and configured:

Storage Engine — Configure local storage, databases, and adapters
API Reference — Explore all available hooks and options
Server Contract — Implement the backend /metrics endpoint

Not sure about implementation details? Review the Introduction for architecture guidance and performance expectations.