DEV Community

Felipe Rohde
Felipe Rohde

Posted on

Reading Umami's source: how a cookieless analytics app is built in Next.js

I use a lot of small analytics scripts on side projects, and at some point I got curious about how the self-hosted ones actually work under the hood. Umami is the one I keep coming back to: it's open source (MIT), it's a Next.js app written in TypeScript, and the whole thing is readable in an afternoon. So I read it. This is a breakdown of the stack and the few ideas in there that I think are worth stealing for your own projects.

Everything below comes from the public repo (github.com/umami-software/umami, master branch, package.json at version 3.5.0 when I looked). File paths are real so you can follow along.

the stack, from package.json

The short version:

  • the Next.js app router for both the dashboard and the API (next dev --turbo, next build --turbo)
  • Next.js 16 and React 19 on the frontend, with @tanstack/react-query, zustand, chart.js, and their own UI kit @umami/react-zen
  • Prisma with PostgreSQL as the default database (the README asks for Postgres 12.14+ and Node 20.19+)
  • optional ClickHouse (@clickhouse/client) for big event volumes, and optional Kafka (kafkajs) in front of it
  • redis for caching, maxmind for geo lookups, isbot for bot filtering, zod for request validation
  • the tracker script is a separate TypeScript bundle built with Rollup
  • tests with Vitest and Playwright, lint and format with Biome, pnpm workspaces for internal packages

Nothing exotic. What's interesting is how it's wired.

one route takes all the traffic

Every pageview and custom event goes to a single endpoint: src/app/api/send/route.ts. It's a plain Next.js route handler exporting POST(request: Request). The flow inside it is roughly:

  1. parse and validate the body with a zod schema (collectionSchema)
  2. check a cache token header, and only hit the database for the website if there's no valid token
  3. pull client info (IP, user agent, device, country) from the request
  4. drop bots with isbot(userAgent) and drop blocked IPs
  5. work out the session and visit ids
  6. save the event

The bot check made me laugh a bit, because instead of an error it just returns this:

if (!process.env.DISABLE_BOT_CHECK && isbot(userAgent)) {
  return json({ beep: 'boop' });
}
Enter fullscreen mode Exit fullscreen mode

A 200 with a joke body. Which is actually the right call: you don't want to tell a scraper anything useful, and you don't want error noise in your logs either.

sessions without cookies

This is the part I came for. Umami doesn't set cookies, so how does it know two pageviews belong to the same person? It derives a deterministic id from things it already has on every request. From src/lib/crypto.ts:

export function uuid(...args: any) {
  if (args.length) {
    return v5(hash(...args, secret()), v5.DNS);
  }

  return process.env.USE_UUIDV7 ? v7() : v4();
}
Enter fullscreen mode Exit fullscreen mode

hash is sha512 over the joined strings, and secret() is a hash of the app secret. Then in src/lib/collection-session.ts the session id is built like this:

const sessionId = uuid(sourceId, ip, userAgent, sessionSalt, distinctId ?? '');
Enter fullscreen mode Exit fullscreen mode

Same website, same IP, same user agent, same salt, same id. No storage on the client at all. The raw IP never needs to be the identifier, it only goes into the hash.

The salt is where the privacy trick is. By default it rotates monthly:

export function getSalt(saltRotation: string | undefined, createdAt: Date): string {
  const value = saltRotation?.trim();

  if (!value) {
    return hash(startOfMonth(createdAt).toUTCString());
  }
  // day/week/month presets, or a fixed custom string
  ...
}
Enter fullscreen mode Exit fullscreen mode

So when the month flips, the same visitor gets a brand new session id and there's no way to link the two. You can set SALT_ROTATION to day or week if you want it even shorter. You lose long term returning-visitor stats, you gain not having a persistent identifier for anyone. For most indie projects that trade is fine.

Visits (one sitting on the site) get their own id on top of that, salted by the hour, and a visit is renewed after 30 minutes of inactivity:

const visitSalt = hash(startOfHour(createdAt).toUTCString());
let visitId = cache?.visitId || uuid(sessionId, visitSalt);
let iat = cache?.iat || now;
if (sessionDrift || (!historical && now - iat > 1800)) {
  visitId = uuid(sessionId, visitSalt);
  iat = now;
}
Enter fullscreen mode Exit fullscreen mode

the cache token handshake

The other thing I liked: the server hands the tracker a signed token, and the tracker sends it back on every following request in an x-umami-cache header. The token carries the website id, session id, visit id and when it was issued. If the token is valid, the route skips the "does this website exist" lookup and the session insert. That's a lot of database round trips saved on a high traffic site, and it's just a JWT, no extra infra.

On the client side, in src/tracker/index.ts, it's a plain fetch with keepalive: true so events still go out when the page is closing:

const res = await fetch(endpoint, {
  keepalive: true,
  method: 'POST',
  body: JSON.stringify({ type, payload }),
  headers: {
    'Content-Type': 'application/json',
    'x-umami-website-id': website as string,
    'x-umami-hostname': hostname,
    ...(typeof cache !== 'undefined' && { 'x-umami-cache': cache }),
  },
  credentials,
});

const data = (await res.json()) as { cache?: string; disabled?: boolean } | null;
if (data) {
  disabled = !!data.disabled;
  cache = data.cache;
}
Enter fullscreen mode Exit fullscreen mode

For single page apps it monkey patches history.pushState and history.replaceState so client side navigations count as pageviews. Old trick, still works.

two databases behind one function

Umami runs on just Postgres for small installs, and on ClickHouse (optionally with Kafka in front) for large ones. The switch lives in src/lib/db.ts and it's tiny:

export async function runQuery(queries: any) {
  if (process.env.CLICKHOUSE_URL) {
    if (queries[KAFKA]) {
      return queries[KAFKA]();
    }

    return queries[CLICKHOUSE]();
  }

  const db = getDatabaseType();

  if (db === POSTGRESQL) {
    return queries[PRISMA]();
  }
}
Enter fullscreen mode Exit fullscreen mode

Every query module passes an object with one implementation per backend, and this picks one based on env vars. No ORM abstraction trying to pretend Postgres and ClickHouse are the same thing. Each backend gets hand written queries that make sense for it. The ClickHouse schema and migrations live in db/clickhouse/, the Prisma schema in prisma/schema.prisma.

I like this a lot for indie stuff. Start with the boring database you already run, and leave a clean seam for the day you actually need something else.

stealing the idea: a tiny cookieless counter in TypeScript

Here's a stripped down version of the session idea I wrote to try it out. Node only, no dependencies besides node:crypto:

import { createHash } from 'node:crypto';

const APP_SECRET = process.env.APP_SECRET ?? 'change-me';

const sha = (...parts: string[]) =>
  createHash('sha512').update(parts.join('')).digest('hex');

function monthSalt(d: Date) {
  const start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1));
  return sha(start.toUTCString());
}

export function sessionId(siteId: string, ip: string, ua: string, at = new Date()) {
  // same inputs in the same month -> same id. next month -> unlinkable
  return sha(siteId, ip, ua, monthSalt(at), sha(APP_SECRET)).slice(0, 32);
}
Enter fullscreen mode Exit fullscreen mode

And a minimal Next.js route handler using it:

// app/api/hit/route.ts
import { sessionId } from '@/lib/session';

export async function POST(req: Request) {
  const ua = req.headers.get('user-agent') ?? '';
  const ip = req.headers.get('x-forwarded-for')?.split(',')[0].trim() ?? '';
  const { site, path } = (await req.json()) as { site: string; path: string };

  const sid = sessionId(site, ip, ua);
  // insert { sid, site, path, at: new Date() } wherever you keep events

  return Response.json({ ok: true });
}
Enter fullscreen mode Exit fullscreen mode

That's maybe 30 lines and you already have unique visitors per month without a cookie banner. Obviously Umami does way more (bot filtering, geo, the cache token, validation, a whole dashboard), but the core idea fits in your head.

what I'm taking from it

  • one ingest route, validated with zod, that does as little work as possible per request
  • deterministic hashed ids plus a rotating salt instead of cookies
  • a signed token round trip to skip repeat database lookups
  • a dumb runQuery switch instead of a clever database abstraction
  • the tracker as its own small bundle, separate from the app

None of this needs a big team. It's a Next.js app with good boundaries, and that's most of the lesson.

sources

I post about indie apps and the stuff behind them on X https://x.com/felipe_rohde and Instagram https://instagram.com/feliperohde.dev.

Top comments (0)