Required dependencies

npm install @clickhouse/client @date-fns/utc @dicebear/collection @dicebear/core \
  @hello-pangea/dnd @prisma/adapter-pg @prisma/client \
  @prisma/extension-read-replicas @react-spring/web \
  @tanstack/react-query @umami/react-zen \
  bcryptjs chalk chart.js chartjs-adapter-date-fns \
  classnames colord cors cross-spawn date-fns date-fns-tz \
  debug del detect-browser dotenv

No native modules, iOS pods, or Android linking steps are required. The tracker and session-recorder scripts are bundled via Rollup (rollup.tracker.config.js, rollup.recorder.config.js) — run those separately if you need standalone browser scripts:

pnpm rollup -c rollup.tracker.config.js
pnpm rollup -c rollup.recorder.config.js

Project setup

1. Drop the source directory into your repo root (or a sub-directory, e.g. packages/umami/).

2. Configure TypeScript paths. The source uses @/ as an alias for src/. In your tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["source/src/*"]
    }
  }
}

3. Configure Next.js to pick up the alias and point to the correct app directory. In next.config.ts (or your own), ensure experimental.serverActions is enabled if you extend server components.

4. Set environment variables. Create .env in the project root:

DATABASE_URL=postgresql://username:password@localhost:5432/umami
# Optional ClickHouse dual-write:
CLICKHOUSE_URL=http://localhost:8123
# Auth secret for JWT / session signing:
APP_SECRET=replace-with-random-secret

5. Generate the Prisma client and run migrations:

npx prisma generate --schema=source/prisma/schema.prisma
npx prisma migrate deploy --schema=source/prisma/schema.prisma

6. (Optional) Seed demo data:

pnpm ts-node source/scripts/seed/index.ts

7. Build and start:

pnpm build
pnpm start

Public API

SeedConfig

// source/scripts/seed/index.ts
export interface SeedConfig {
  days: number;    // how many historical days to generate
  clear: boolean;  // whether to truncate existing data before seeding
  verbose: boolean; // print per-batch progress
}

Pass a SeedConfig to the seeding entry point when programmatically populating a test or staging database. Use days to control the size of the generated dataset and clear to guarantee a clean state before each seed run.

SeedResult

// source/scripts/seed/index.ts
export interface SeedResult {
  websites: number;
  sessions: number;
  events: number;
  eventData: number;
  revenue: number;
}

Returned by the seed runner to report how many records were inserted per entity type. Useful in CI pipelines that assert a minimum row count after seeding.

useWebsiteMetricsQuery (hook)

// source/src/components/hooks/queries/useWebsiteMetricsQuery.ts
// re-exported from source/src/components/hooks/index.ts
export function useWebsiteMetricsQuery(
  websiteId: string,
  params: Record<string, unknown>
): UseQueryResult<WebsiteMetrics>;

React Query wrapper for the /api/websites/:id/metrics endpoint. Use it in any client component that needs page-view counts, unique visitors, bounce rate, or time-on-page for a given website and date range. Internally it honours the shared @tanstack/react-query cache.

Working examples

Scenario - Seeding a staging database programmatically

Run the seed script from a custom Node.js script to populate a staging Postgres database with 30 days of synthetic traffic for both the blog and SaaS demo sites.

// scripts/seedStaging.ts
import 'dotenv/config';
import type { SeedConfig, SeedResult } from '../source/scripts/seed/index.js';

// Dynamically import because the seed module uses top-level await internally
const { seed } = await import('../source/scripts/seed/index.js');

const config: SeedConfig = {
  days: 30,
  clear: true,
  verbose: true,
};

const result: SeedResult = await seed(config);

console.log('Seeding complete:', result);
// { websites: 2, sessions: 1840, events: 9200, eventData: 2300, revenue: 410 }

Scenario - Consuming analytics hooks in a custom Next.js dashboard

Add a live visitor count widget to your own Next.js app by importing Umami's query hook directly.

// app/dashboard/LiveCount.tsx
'use client';

import { useActiveUsersQuery } from '../source/src/components/hooks/index.js';

interface Props {
  websiteId: string;
}

export default function LiveCount({ websiteId }: Props) {
  const { data, isLoading } = useActiveUsersQuery(websiteId);

  if (isLoading) return <span>Loading...</span>;

  return (
    <div>
      <strong>{data?.x ?? 0}</strong> active visitors right now
    </div>
  );
}

Scenario - Rendering Umami SVG icons in your UI

Import named SVG icon components exported from the SVG index for use inside your own design system.

// components/NavItem.tsx
import { Dashboard, Reports, Gear } from '../source/src/components/svg/index.js';

export function NavItem({ label }: { label: string }) {
  const icons: Record<string, JSX.Element> = {
    Dashboard: <Dashboard />,
    Reports: <Reports />,
    Settings: <Gear />,
  };

  return (
    <li className="nav-item">
      {icons[label] ?? null}
      <span>{label}</span>
    </li>
  );
}

File walkthrough

• .github/ - GitHub Actions workflows for continuous integration, cloud deployment, and issue triage.
• cypress/ - Browser-level E2E tests; support/e2e.ts registers custom Cypress commands.
• db/ - Vendor-neutral SQL: ClickHouse schema + incremental migrations; PostgreSQL data-migration helpers.
• docker/ - proxy.ts is a lightweight reverse-proxy entry-point used inside the Docker image.
• podman/ - Drop-in Podman Compose alternative; documented in podman/README.md.
• prisma/ - schema.prisma defines all entities (Website, Session, WebsiteEvent, Revenue, etc.); numbered migration folders track schema evolution.
• public/ - Static files (favicon, images) served by Next.js at the root path.
• scripts/ - Developer tooling: seed/index.ts orchestrates demo-data generation using site configs in scripts/seed/sites/.
• src/ - Core application: Next.js App Router pages under app/, shared React components under components/, permission helpers under permissions/, and the component barrel export at src/index.ts.
• next.config.ts - Configures Next.js output, webpack aliases, and environment variable exposure.
• prisma.config.ts - Configures the Prisma adapter (PrismaPg) and optional read-replica extension.
• rollup.tracker.config.js / rollup.recorder.config.js - Bundle the browser-side tracking and session-replay scripts as standalone UMD files.
• tsup.config.js - Bundles src/index.ts as a distributable component library.

Common pitfalls and fixes

• DATABASE_URL not set at build time - Prisma client generation and prisma migrate deploy both read this variable; ensure it is exported in your shell or .env before running pnpm build.
• @/ path alias not resolved by Jest - Add moduleNameMapper: { '^@/(.*)$': '<rootDir>/source/src/$1' } to jest.config.ts.
• Prisma client generated to the wrong location - The schema uses output = "../../src/generated/prisma/client" relative to prisma/; if you move the schema, update generator client { output = ... } accordingly.
• 'use client' boundary errors - All hooks in src/components/hooks/index.ts are client-only (the file starts with 'use client'); never import them inside Server Components or API route handlers.
• ClickHouse dual-write not activating - CLICKHOUSE_URL must be set and the ClickHouse schema applied (db/clickhouse/schema.sql) before the application starts; missing the var silently disables dual-write without crashing.
• ESM/CJS interop with seed scripts - scripts/seed/index.ts uses import + top-level await; run with tsx or ts-node --esm, not plain ts-node, to avoid SyntaxError: Cannot use import statement.

Vibe-coding prompt template

I have dropped the Umami Analytics source (umami@3.1.0) into `source/` inside my
project. I also have USAGE.md in the project root describing the real exports and
setup steps.

Please help me integrate Umami into my existing Next.js 14 + TypeScript project
step by step:

1. Read USAGE.md and source/src/index.ts to understand what is exported.
2. Add the required path alias `@/ -> source/src/` to tsconfig.json and
   next.config.ts.
3. Wire the DATABASE_URL and APP_SECRET environment variables.
4. Run `prisma generate` and `prisma migrate deploy` against source/prisma/schema.prisma.
5. Create a QueryClientProvider wrapper that satisfies the @tanstack/react-query
   dependency required by hooks in source/src/components/hooks/index.ts.
6. Add a /dashboard page that uses `useWebsiteMetricsQuery` and `useActiveUsersQuery`
   from source/src/components/hooks/index.ts to display live stats for a hardcoded
   websiteId.
7. Optionally import SVG icons from source/src/components/svg/index.ts for the nav.

Only use symbols that exist in the file excerpts provided in USAGE.md. Do not invent
new API surface. Show me each file you create or modify with the full diff.

License and credit

Umami is released under the MIT License (see source/LICENSE). Upstream repository and package: github.com/umami-software/umami, npm package user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.