Litemetrics

Open-source analytics you can integrate into your product.
Give your users a beautiful analytics dashboard in 5 minutes.

Live Demo • Quick Start • Packages • Deploy • Docs • Issues

AI Agent Skill:  npx skills add metehankurucu/litemetrics
_{Gives your AI coding agent (Claude Code, Cursor, Windsurf) full knowledge of Litemetrics integration patterns.}

Why Litemetrics?

Embed into your product	Drop a full analytics stack into your app — tracker, server, query API, and a pre-built dashboard UI. Your customers get analytics without you building anything.
Your brand, your colors	10 built-in theme presets. CSS custom properties for full control. Dark mode included. Ship analytics that look like they belong in your app.
Multi-tenant ready	Each customer gets isolated analytics via site_id. One database, zero cross-contamination. Built for SaaS from day one.
Lightweight tracker	~3 KB gzipped. Auto-tracks pageviews, sessions, scroll depth, button clicks, outbound links — or go fully manual.
ClickHouse & MongoDB	Choose the database that fits. ClickHouse for speed at scale, MongoDB for simplicity. Swap with one env var.
One-click deploy	Docker Compose, Railway, or a single Docker container. Up and running in under a minute.

Quick Start

1. Add a dashboard to your app

npm install @litemetrics/ui

import { LitemetricsProvider, AnalyticsDashboard } from '@litemetrics/ui';

function CustomerDashboard({ customerId }) {
  return (
    <LitemetricsProvider baseUrl="/api/stats" siteId={customerId}>
      <AnalyticsDashboard theme="midnight" />
    </LitemetricsProvider>
  );
}

2. Add tracking to your site

<script src="https://your-server.com/litemetrics.js"></script>
<script>
  Litemetrics.createTracker({
    siteId: 'your-site-id',
    endpoint: 'https://your-server.com/api/collect'
  });
</script>

3. Add the server (Express)

npm install @litemetrics/node

import express from 'express';
import { createCollector } from '@litemetrics/node';

const app = express();
app.use(express.json());

const collector = await createCollector({
  db: { url: 'http://localhost:8123' },
});

app.all('/api/collect', (req, res) => collector.handler()(req, res));
app.all('/api/stats', (req, res) => collector.queryHandler()(req, res));

app.listen(3002);

For MongoDB: db: { adapter: 'mongodb', url: 'mongodb://localhost:27017/myapp' }

4. Run the mobile app (Expo)

cd apps/mobile
bun install
bun run start

For platform-specific launches:

bun run ios
bun run android

5. Query from the terminal (CLI)

bun add -g @litemetrics/cli

# Configure once
export LITEMETRICS_URL=https://your-server.com
export LITEMETRICS_ADMIN_SECRET=your-secret
export LITEMETRICS_SITE_ID=your-site-id

# Overview of all metrics
litemetrics overview -p 7d --compare

# Top pages
litemetrics stats top_pages -p 30d -l 10

# Time series
litemetrics timeseries visitors -p 30d -g day

# JSON output for AI agents
litemetrics overview -p 7d -f json

See packages/cli/README.md for all commands.

Deploy

Docker Compose (recommended)

git clone https://github.com/metehankurucu/litemetrics.git
cd litemetrics
ADMIN_SECRET=your-secret docker compose up -d

Open http://localhost:3002 for the dashboard.

Docker (standalone)

docker build -t litemetrics .
docker run -p 3002:3002 \
  -e CLICKHOUSE_URL=http://your-clickhouse:8123 \
  -e ADMIN_SECRET=your-secret \
  litemetrics

Railway (one click)

1. Click the Deploy on Railway button above
2. Add a ClickHouse plugin (or MongoDB)
3. Set CLICKHOUSE_URL (or MONGODB_URL) and ADMIN_SECRET
4. Done — dashboard, API, and tracker served from one container

Environment Variables

Variable	Description	Default
DB_ADAPTER	Database adapter (clickhouse or mongodb)	clickhouse
CLICKHOUSE_URL	ClickHouse connection URL	http://localhost:8123
MONGODB_URL	MongoDB connection string	mongodb://localhost:27017/litemetrics
ADMIN_SECRET	Secret for admin access and site management	(none)
PORT	Server port	3002
GEOIP	Enable GeoIP lookup	true
TRUST_PROXY	Trust X-Forwarded-For headers	true

DATABASE_URL and LITEMETRICS_ADMIN_SECRET also work as aliases.

Architecture

┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│                  │  POST   │                  │  GET    │                  │
│  @litemetrics/   │ /collect│  @litemetrics/   │ /stats  │  @litemetrics/   │
│  tracker         ├────────>│  node            │<────────┤  dashboard       │
│                  │         │  (collector)     │         │                  │
│  ~3KB, browser   │ events  │  ClickHouse /    │ queries │  React UI        │
│                  │         │  MongoDB         │         │                  │
└──────────────────┘         └──────────────────┘         └──────────────────┘
     Browser / App                Your Server           ▲     Dashboard
                                                        │
                                                   ┌────┴─────────────┐
                                                   │  @litemetrics/   │
                                                   │  cli             │
                                                   │  Terminal / AI   │
                                                   └──────────────────┘

The tracker handles session management, visitor IDs, batching, and SPA detection client-side. The server stores events and runs queries. The CLI provides terminal access to all analytics data — designed for both humans and AI agents. The Docker image bundles everything into a single container.

Packages

Package	Description
@litemetrics/ui	Pre-built React dashboard components (10 themes, dark mode, CSS variables)
@litemetrics/tracker	Browser tracker (~3 KB gzipped)
@litemetrics/node	Server collector, ClickHouse/MongoDB adapters, query API
@litemetrics/react	React provider and hooks
@litemetrics/react-native	React Native / Expo provider
@litemetrics/client	Typed client for reading analytics data
@litemetrics/cli	CLI tool for querying analytics and managing sites
@litemetrics/core	Shared types and constants

Apps

App	Description
@litemetrics/dashboard	Analytics dashboard (React + Vite + Tailwind)
@litemetrics/server	Self-hosted server (serves dashboard + API)
@litemetrics/mobile	Native mobile analytics app (Expo Router + React Native)
@litemetrics/landing	Landing page (React + Vite + Tailwind)

Metrics

pageviews · visitors · sessions · events · conversions · top_pages · top_referrers · top_countries · top_cities · top_events · top_conversions · top_exit_pages · top_transitions · top_scroll_pages · top_button_clicks · top_link_targets · top_devices · top_browsers · top_os · top_os_versions · top_device_models · top_app_versions · top_utm_sources · top_utm_mediums · top_utm_campaigns · top_utm_terms · top_utm_contents · top_channels · timeseries · retention

Auto Events & Insights

• Auto events are tagged with event_source=auto and a subtype (scroll_depth, button_click, link_click, outbound_click).
• Manual track() events default to event_source=manual and event_subtype=custom.
• All metrics and time series support segmentation filters (geo, device, UTM, referrer, event metadata).
• The dashboard Insights view surfaces exit pages, transitions, scroll-heavy pages, and click hotspots.

Docs

• Getting Started
• Integration Guide — React, React Native, Next.js, Vue, Python, PHP, Ruby, Go
• API Reference
• Dashboard
• CLI
• Mobile App
• Self-Hosting
• Scaling

Development

git clone https://github.com/metehankurucu/litemetrics.git
cd litemetrics
bun install
bun run build

License

MIT