https://github.com/metehankurucu/litemetrics

Open-source analytics SDK you can integrate into your product. Give your users a beautiful analytics dashboard in 5 minutes.
https://github.com/metehankurucu/litemetrics

analytics analytics-tracking litemetrics react self-hosted tracking

Last synced: 2 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/metehankurucu/litemetrics
Owner: metehankurucu
License: mit
Created: 2026-02-07T13:35:44.000Z (5 months ago)
Default Branch: main
Last Pushed: 2026-03-24T20:18:18.000Z (3 months ago)
Last Synced: 2026-03-26T01:28:04.392Z (3 months ago)
Topics: analytics, analytics-tracking, litemetrics, react, self-hosted, tracking
Language: TypeScript
Homepage: https://litemetrics.dev
Size: 3.38 MB
Stars: 3
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

          


  



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

```bash

npm install @litemetrics/ui

```

```tsx

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

function CustomerDashboard({ customerId }) {

  return (

    

      

    

  );

}

```

### 2. Add tracking to your site

```html

  Litemetrics.createTracker({

    siteId: 'your-site-id',

    endpoint: 'https://your-server.com/api/collect'

  });

```

### 3. Add the server (Express)

```bash

npm install @litemetrics/node

```

```ts

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)

```bash

cd apps/mobile

bun install

bun run start

```

For platform-specific launches:

```bash

bun run ios

bun run android

```

### 5. Query from the terminal (CLI)

```bash

bun add -g @litemetrics/cli

```

```bash

# 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`](./packages/cli/README.md) for all commands.




## Deploy

### Docker Compose (recommended)

```bash

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)

```bash

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`](./packages/ui) | Pre-built React dashboard components (10 themes, dark mode, CSS variables) |

| [`@litemetrics/tracker`](./packages/tracker) | Browser tracker (~3 KB gzipped) |

| [`@litemetrics/node`](./packages/node) | Server collector, ClickHouse/MongoDB adapters, query API |

| [`@litemetrics/react`](./packages/react) | React provider and hooks |

| [`@litemetrics/react-native`](./packages/react-native) | React Native / Expo provider |

| [`@litemetrics/client`](./packages/client) | Typed client for reading analytics data |

| [`@litemetrics/cli`](./packages/cli) | CLI tool for querying analytics and managing sites |

| [`@litemetrics/core`](./packages/core) | Shared types and constants |

### Apps

| App | Description |

|-----|-------------|

| [`@litemetrics/dashboard`](./apps/dashboard) | Analytics dashboard (React + Vite + Tailwind) |

| [`@litemetrics/server`](./apps/server) | Self-hosted server (serves dashboard + API) |

| [`@litemetrics/mobile`](./apps/mobile) | Native mobile analytics app (Expo Router + React Native) |

| [`@litemetrics/landing`](./apps/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](./docs/getting-started.md)

- [Integration Guide](./docs/integration-guide.md) — React, React Native, Next.js, Vue, Python, PHP, Ruby, Go

- [API Reference](./docs/api-reference.md)

- [Dashboard](./docs/dashboard.md)

- [CLI](./packages/cli/README.md)

- [Mobile App](./apps/mobile/README.md)

- [Self-Hosting](./docs/self-hosting.md)

- [Scaling](./docs/scaling.md)




## Development

```bash

git clone https://github.com/metehankurucu/litemetrics.git

cd litemetrics

bun install

bun run build

```




## License

MIT

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/metehankurucu/litemetrics

Awesome Lists containing this project

README

Litemetrics