# How to Vibe Code Your Own Umami (and Stop Paying for It)

> Privacy-Focused Web Analytics

- Site: https://umami.is
- Category: Web Analytics & SaaS
- Verdict: **Solid side project** (75/100 vibecodeable)
- Estimated effort: 2-3 weeks part-time

## Verdict

Build a personal-use clone of Umami for self-hosting in a couple of weeks, but paying for Umami Cloud or self-hosting the official open-source binary is more pragmatic than writing your own from scratch.

Umami is fundamentally a Next.js frontend wrapped around a relational database with a tiny vanilla JS ingestion tracker. Vibecoding the core loop—collecting telemetry via an API route and displaying it with Recharts—is very achievable. However, handling high-concurrency event writes without database lockups and writing performant SQL aggregations for time-series charts will require iterative query tuning and index optimization with your AI coding agent.

### What you can't replicate

- The existing 38,000+ GitHub star community and brand trust
- Production-tested bot filtering heuristics refined over years of edge cases

## What it does

A privacy-first, lightweight web analytics platform that tracks traffic, events, and metrics without using cookies or collecting personally identifiable information.

### Core features

- Ultra-lightweight tracking script (<2KB) collecting events without cookies
- High-throughput write-optimized ingestion API endpoint
- Real-time analytics dashboard with pageviews, referrers, and custom events
- Aggregated time-series query performance across millions of rows
- Bot and crawler filtering heuristics
- Multi-website management per user
- Custom event payload capture and breakdown

## The business

### Pricing

- Self-Hosted: Free — Open source (MIT license). Free forever if self-hosted.
- Hobby: Free — Managed cloud tier for personal projects.
- Pro: $20 / month — For growing teams and businesses.
- Business: $200 / month — For high-volume operations.

### Funding

$1.5M raised.
- Pre-seed (July 2022)
Investors: Race Capital

Founded 2020.
Team size: 10-15.

## The hard parts

- Ingestion scale: handling heavy burst writes without locking the database
- Query optimization: fast time-series aggregation over massive pageview tables
- Client script constraints: maintaining a dependency-free tracker under 2KB that executes asynchronously
- Bot filtering accuracy: filtering automated web scrapers without dropping legitimate users

## How to vibe code Umami

### Prerequisites

- Node.js (free): Runtime environment for building and running the Next.js application.
- GitHub (free): Version control and automated deployment trigger.

### Recommended AI tools

- Claude Code: Best-in-class terminal agent for scaffolding the full Next.js stack, database schema, and tracking script end-to-end.
- Cursor: Ideal for fine-tuning dashboard charts, UI components, and SQL aggregation queries with direct code diff reviews.

### Stack

- Frontend: Next.js App Router, Tailwind CSS, Shadcn/ui, Recharts
- Backend: Next.js API Routes / Node.js handlers
- Database: PostgreSQL (via Neon or Supabase)
- Auth: better-auth
- Payments: None (personal-use clone)
- Other: Prisma ORM for database migrations and queries, Ultra-lightweight vanilla JS tracker script (<2KB)

### Hosting

- Vercel (Hosting the Next.js dashboard and serverless API ingestion endpoints on the Hobby tier.): $0/mo
- Neon (Serverless PostgreSQL database storing pageviews, sessions, and website configurations.): $0/mo

### Build guide

1. **Scaffold Next.js App & Database Schema** — Initialize the Next.js project with Tailwind CSS, configure Prisma ORM, and set up the PostgreSQL database schema for websites, sessions, and website events.

```
Create a new Next.js App Router project in TypeScript with Tailwind CSS and Shadcn/ui. Initialize Prisma ORM configured for PostgreSQL. Create a database schema with models for 'Website' (id, name, domain, userId, createdAt), 'Session' (id, websiteId, hostname, browser, os, device, country, createdAt), and 'WebsiteEvent' (id, websiteId, sessionId, url, eventName, eventData, createdAt). Add proper indexes on websiteId and createdAt for high-performance time-series aggregations. Provide the complete prisma/schema.prisma file and an initial migration script.
```

2. **Build the Tracker Ingestion API** — Create a high-performance, lightweight API endpoint that receives telemetry data, parses user-agent headers for device and browser stats, and writes records asynchronously without blocking.

```
Implement a Next.js API route at POST /api/send that acts as the telemetry ingestion endpoint. It must accept a JSON payload containing payload type, website token, url, referrer, and optional custom event data. Extract client metadata from request headers (user-agent for browser/OS/device estimation via standard lightweight parsing, and geo-ip headers if available). Implement bot filtering heuristics to discard requests from common automated web crawlers and scrapers. Save the session and event data efficiently to PostgreSQL using Prisma, returning a 200 OK status immediately. Include input validation and error handling.
```

3. **Write the Vanilla JS Tracker Script** — Develop the ultra-lightweight, dependency-free JavaScript snippet that website owners embed to collect pageviews and custom events asynchronously.

```
Create a vanilla JavaScript tracking script (target size <2KB minified) designed to be embedded in external websites via a script tag. The script should automatically capture page views on load and history changes (SPA navigation), record referrer data, and expose a global `umami.track(eventName, eventData)` function for custom event tracking. It must send data asynchronously via `navigator.sendBeacon` or `fetch` with `keepalive` to the `/api/send` endpoint without setting any cookies or storing PII. Provide instructions on how to bundle or minify this script.
```

4. **Implement Analytics Dashboard & Aggregation Queries** — Build the core dashboard views and SQL aggregation queries to display real-time metrics, pageviews, referrers, and custom events over custom date ranges.

```
Build a dashboard page in the Next.js App Router at /websites/[id] that displays web analytics metrics for a selected website. Implement backend API routes and helper query functions using Prisma/SQL to aggregate total pageviews, visitors, bounces, and average visit time grouped by time ranges (today, last 7 days, last 30 days). Include breakdown lists for top URLs, referrers, browsers, operating systems, and countries. Use Recharts to render clean time-series charts for traffic over time.
```

5. **Add Authentication & Multi-Website Management** — Integrate better-auth for secure user authentication and build settings UI allowing users to register new websites and retrieve their tracker script tags.

```
Integrate better-auth into the Next.js application supporting email/password and GitHub sign-in. Secure all analytics dashboard routes so users can only view websites they own. Build a dashboard home view allowing users to create new website entries (specifying a name and domain), generate a unique tracking ID/token, and view the exact HTML script tag snippet required to embed tracking on their external sites.
```

6. **Polish, Bot Filtering & Deployment** — Refine bot detection filters, add loading states, handle empty states, and deploy the application to Vercel connected to Neon Postgres.

```
Review and enhance the bot-filtering utility in the ingestion route to filter out known search engine indexers and automated scanners based on user-agent strings and IP patterns. Add smooth loading skeletons, date-range filter pickers, and clean empty states across the analytics dashboard. Ensure all environment variables are correctly documented in a .env.example file for seamless deployment on Vercel and Neon.
```

### Cost vs paying

**Starting costs (one-time):**

- AI Coding Assistant (Claude Pro / Cursor): $20
- Custom Domain (optional): $12/yr
- Total: ~$32 one-time

**Ongoing costs (monthly):**

- Vercel Hobby Hosting: $0/mo
- Neon Serverless Postgres: $0/mo
- Total: $0/mo

- Paying for the SaaS instead: $20/mo (Pro tier)
- Build time: 25-35 hours
- AI tool credits: $20 (one month of Claude Pro / Cursor)
- Break-even: 0 months (self-hosted free tier)

## Sources

- [Umami Official Website & Documentation](https://umami.is)
- [GitHub - Official Umami Repository](https://github.com/umami-software/umami)
- [GlobeNewswire - Umami $1.5M Pre-Seed Announcement](https://www.globenewswire.com/news-release/2022/07/19/2482029/0/en/Umami-Raises-1-5-Million-Pre-Seed-Funding-Round-Led-By-Race-Capital.html)
- [FreeTier.co - Umami Cloud Pricing & Tier Breakdown](https://freetier.co/tool/umami)