Umami Analytics Setup in MakerKit

Umami is a privacy-focused analytics platform that tracks page views and events without cookies. Because it does not use cookies or collect personal data, you can use Umami without displaying cookie consent banners in the EU. Umami can be self-hosted for complete data ownership or used via Umami Cloud.

Why Choose Umami

Use Umami when: You want simple, clean metrics without privacy concerns. Ideal for landing pages, documentation sites, and applications where marketing attribution is not critical.

Prerequisites

Before starting:

• Create an Umami account at umami.is or self-host
• Create a website in your Umami dashboard
• Note your Website ID and Script URL

In Umami Cloud, find these at: Settings > Websites > Your Website > Edit.

Installation

Install the Umami plugin using the MakerKit CLI:

npx @makerkit/cli@latest plugins install

Select Umami from the list. This creates the plugin at packages/plugins/umami.

Add the plugin as a dependency to the analytics package:

pnpm add "@kit/umami@workspace:*" --filter "@kit/analytics" -D

Configuration

Register the provider in your analytics configuration:

import { createUmamiAnalyticsService } from '@kit/umami';
import { createAnalyticsManager } from './analytics-manager';
import type { AnalyticsManager } from './types';
export const analytics: AnalyticsManager = createAnalyticsManager({
  providers: {
    umami: createUmamiAnalyticsService,
  },
});

Add environment variables:

NEXT_PUBLIC_UMAMI_HOST=https://cloud.umami.is/script.js
NEXT_PUBLIC_UMAMI_WEBSITE_ID=your-website-id

Self-Hosted Configuration

If self-hosting Umami, point to your instance:

NEXT_PUBLIC_UMAMI_HOST=https://analytics.yourdomain.com/script.js
NEXT_PUBLIC_UMAMI_WEBSITE_ID=your-website-id

Replace the URL with the path to your Umami instance's tracking script.

Environment Variables

Development Configuration

By default, Umami does not track localhost. Enable it for development testing:

NEXT_PUBLIC_UMAMI_HOST=https://cloud.umami.is/script.js
NEXT_PUBLIC_UMAMI_WEBSITE_ID=your-website-id
NEXT_PUBLIC_UMAMI_DISABLE_LOCALHOST_TRACKING=false

Verification

After configuration:

1. Deploy to a non-localhost environment (or enable localhost tracking)
2. Open your application and navigate between pages
3. Check your Umami dashboard > Realtime
4. Confirm page views appear

Custom Event Tracking

Umami tracks page views automatically. For custom events:

import { analytics } from '@kit/analytics';
void analytics.trackEvent('Button Clicked', {
  button: 'signup',
  location: 'header',
});

Events appear in Umami under Events in your website dashboard.

Using with Other Providers

Umami can run alongside other providers:

import { createUmamiAnalyticsService } from '@kit/umami';
import { createPostHogAnalyticsService } from '@kit/posthog/client';
import { createAnalyticsManager } from './analytics-manager';
export const analytics = createAnalyticsManager({
  providers: {
    umami: createUmamiAnalyticsService,
    posthog: createPostHogAnalyticsService,
  },
});

This setup provides Umami's clean metrics alongside PostHog's product analytics.

Self-Hosting Umami

Umami can be self-hosted using Docker:

version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    ports:
      - '3001:3000'
    environment:
      DATABASE_URL: postgresql://user:pass@db:5432/umami
      DATABASE_TYPE: postgresql
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - ./data:/var/lib/postgresql/data

Self-hosting gives you:

• Complete data ownership
• No usage limits
• Custom data retention policies
• Compliance with data residency requirements

Limitations

Umami is intentionally simple. It does not provide:

• User identification (analytics.identify() is a no-op)
• Session replay
• Feature flags
• Server-side tracking
• Funnel analysis

If you need these features, consider PostHog instead.

Troubleshooting

No data appearing

• Verify you are not on localhost (or enable localhost tracking)
• Check that the Website ID matches your Umami dashboard
• Confirm the script URL is correct and accessible

Ad blocker interference

Umami is sometimes blocked by ad blockers. If this is an issue:

1. Self-host Umami on a subdomain (e.g., analytics.yourdomain.com)
2. Use a generic script path (e.g., /stats.js instead of /script.js)

Events not tracked

• Ensure event names and properties are strings
• Check that the event appears in Umami's Events tab, not just Page Views

Next Steps

• Learn about Analytics and Events for event tracking patterns
• Consider PostHog if you need user identification or feature flags
• Create a custom provider for other analytics services