@devalxui/kova-analytics

v1.0.0

Published

13 days ago

Zero-config privacy-first analytics with real-time dashboard. No database required. Auto-tracks pageviews, clicks, scroll depth, forms, custom events. Works with any framework.

0High
0Medium
0Low

devalxui

analytics tracking pageviews privacy no-cookie dashboard real-time custom-events next.js express lightweight self-hosted gdpr kova

kova-analytics

Zero-config, privacy-first analytics with a real-time dashboard. No database required. No cookies. GDPR compliant.

Drop it in, add one line of code, get a full analytics dashboard at /kova-analytics.

Features

Zero config — works out of the box with file-based storage
Real-time dashboard — live visitors, pageviews, events, all updating live
Auto-tracking — pageviews, clicks, scroll depth, form submissions, UTM params
Custom events — kova.track("signup", { plan: "pro" })
SPA support — tracks pushState/replaceState navigation
No cookies — uses sessionStorage + localStorage only
Privacy first — respects Do Not Track, no third-party requests
Lightweight script — ~3KB tracking snippet
Geo detection — country/city from IP (optional)
Password protected — dashboard requires authentication
Customizable theme — dark, light, or custom colors
API access — query your analytics programmatically
Multiple storage backends — file (default), memory, PostgreSQL, or custom
Works everywhere — Next.js, Express, Hono, Bun, Deno, plain Node

Quick Start

Next.js (App Router)

npm install @devalxui/kova-analytics

// app/kova-analytics/[[...path]]/route.ts
import { withKovaAnalytics } from "@devalxui/kova-analytics/next";

const { handler } = withKovaAnalytics({
  password: "your-secret-password",
});

export const GET = handler;
export const POST = handler;

// app/layout.tsx
import { KovaAnalytics } from "@devalxui/kova-analytics/react";

export default function Layout({ children }) {
  return (
    <html>
      <body>
        {children}
        <KovaAnalytics endpoint="/kova-analytics" />
      </body>
    </html>
  );
}

Done. Visit /kova-analytics to see your dashboard.

Express

import express from "express";
import { kovaAnalytics } from "@devalxui/kova-analytics/express";

const app = express();

app.use(kovaAnalytics({
  password: "your-secret-password",
}));

app.listen(3000);

Any framework (Hono, Bun, Deno)

import { createHandler } from "@devalxui/kova-analytics";

const handler = createHandler({
  password: "your-secret-password",
});

// Use with any framework that supports Request/Response

Script tag (no framework)

<script src="https://yoursite.com/kova-analytics/script.js"></script>

Custom Events

// Track anything
kova.track("signup", { plan: "pro", source: "landing" });
kova.track("purchase", { product: "hoodie", price: 59.99 });
kova.track("video_play", { title: "Demo Video" });

Configuration

withKovaAnalytics({
  // Storage
  storage: "file",              // "file" | "memory" | "postgres" | "custom"
  filePath: "./analytics.json", // file storage path
  postgresUrl: "postgres://...",// for postgres storage

  // Dashboard
  dashboardPath: "/kova-analytics", // dashboard URL
  password: "secret",           // dashboard password
  username: "admin",            // dashboard username

  // Tracking
  trackClicks: true,            // auto-track clicks
  trackScrollDepth: true,       // auto-track scroll depth
  trackForms: true,             // auto-track form interactions

  // Geo
  enableGeo: true,              // IP-based country/city detection

  // Real-time
  liveTimeout: 30,              // seconds before visitor considered gone

  // Theme
  theme: "dark",                // "dark" | "light" | "custom"
  accentColor: "#f5f0e8",      // accent color
  backgroundColor: "#0a0a0a",  // background color

  // API
  enableApi: true,              // enable /stats and /live API endpoints
  apiKey: "your-api-key",       // optional API key
});

API Endpoints

When enableApi is true:

GET  /kova-analytics/stats?period=7d    # Dashboard stats
GET  /kova-analytics/live               # Live visitors
POST /kova-analytics/track              # Ingest tracking data
GET  /kova-analytics/script.js          # Tracking script

Auth: Authorization: Bearer {password} header or ?token={password} query param.

Dashboard

The dashboard shows:

Live visitors — real-time with path, device, country
Pageviews timeline — hourly or daily chart
Top pages — most visited pages
Top referrers — where traffic comes from
Devices — desktop / mobile / tablet breakdown
Browsers & OS — Chrome, Firefox, Safari, etc.
Countries — visitor geography
UTM campaigns — source, medium, campaign tracking
Custom events — your tracked events ranked
Scroll depth — how far visitors scroll
Form analytics — submissions vs abandons

Storage Backends

File (default)

No setup needed. Stores everything in ./kova-analytics.json.

Memory

For serverless or testing. Data resets on restart.

PostgreSQL

withKovaAnalytics({
  storage: "postgres",
  postgresUrl: "postgres://user:pass@host:5432/db",
});

Tables are auto-created on first use.

Custom

withKovaAnalytics({
  storage: "custom",
  customStorage: myCustomAdapter, // implements StorageAdapter interface
});

License

MIT