AGENTS.md

This file provides guidance for AI coding agents working in this repository.

Project overview

Umami is a privacy-focused web analytics platform built with Next.js 15, React 19, and TypeScript.

Primary database: PostgreSQL
Optional analytics backend: ClickHouse
Optional cache/session backend: Redis

Development rules

Assume a dev server is already running on port 3001.
Do not start another dev server.
Use pnpm (not npm or yarn).
Avoid destructive shell commands unless explicitly requested.
Ask before running git commit or git push.

Common commands

# Development
pnpm dev
pnpm build
pnpm start

# Database
pnpm build-db
pnpm update-db
pnpm check-db
pnpm seed-data

# Code quality
pnpm lint
pnpm format
pnpm check
pnpm test

# Build specific parts
pnpm build-tracker
pnpm build-geo

Architecture

src/app/: Next.js App Router routes and API endpoints
src/components/: UI components and hooks
src/lib/: shared utilities and infrastructure helpers
src/queries/: data access layer (Prisma + raw SQL)
src/store/: Zustand stores
src/tracker/: standalone client tracking script
prisma/: schema and migrations

Key implementation patterns

API request validation

Use Zod + parseRequest in API handlers:

const schema = z.object({ /* fields */ });
const { body, error } = await parseRequest(request, schema);
if (error) return error();

Authentication

JWT via Authorization: Bearer <token>
Share token via x-umami-share-token
Role model: admin, manager, user

Client data fetching

React Query defaults: staleTime 60s, no retry, no refetch on window focus

Styling

CSS Modules with CSS variables and theme support

Environment variables

Common env vars:

DATABASE_URL
APP_SECRET
CLICKHOUSE_URL
REDIS_URL
BASE_PATH
DEBUG

Runtime requirements

Node.js 18.18+
PostgreSQL 12.14+
pnpm

1.9 KiB Raw Blame History