Analytics

Umami analytics integration

Analytics

What's Included

  • Umami analytics integration (privacy-friendly, cookie-free)
  • Runtime configuration via environment variables
  • Automatic script injection (client-side only)
  • Localhost detection (skips tracking in development)

Setup

Umami is optional and configured via environment variables:

NUXT_PUBLIC_UMAMI_HOST=https://analytics.yourdomain.com
NUXT_PUBLIC_UMAMI_ID=your-site-id

If these variables are not set, the analytics plugin is not loaded and no tracking script is injected.

How It Works

The umami.client.ts plugin:

  1. Reads NUXT_PUBLIC_UMAMI_HOST and NUXT_PUBLIC_UMAMI_ID from runtime config
  2. Skips injection if either is missing
  3. Skips injection on localhost in production mode
  4. Injects the Umami tracking script into the page <head>

Why Umami?

  • Privacy-friendly — no cookies, GDPR-compliant out of the box
  • Self-hosted — you own your data
  • Lightweight — ~2KB tracking script
  • Open source — free to self-host

Self-Hosting Umami

You can run Umami alongside your app using Docker:

  1. Deploy Umami (see umami.is)
  2. Create a website in the Umami dashboard
  3. Copy the Website ID
  4. Set NUXT_PUBLIC_UMAMI_HOST and NUXT_PUBLIC_UMAMI_ID in your frontend environment

Verification

  1. Visit your deployed website and view the page source (Ctrl+U)
  2. Search for data-website-id — you should see the Umami tracking script
  3. Check your Umami dashboard for page views and real-time visitors

In development mode, check the browser console — missing variables will show a warning: [Umami] Tracking disabled: NUXT_PUBLIC_UMAMI_HOST or NUXT_PUBLIC_UMAMI_ID not configured

Troubleshooting

Script not appearing — Verify environment variables are set with NUXT_PUBLIC_ prefix and restart the application.

No data in Umami dashboard — Verify the website ID matches, the Umami host URL is accessible, and CORS is configured on your Umami instance.

CSP errors — The CSP in nuxt.config.ts includes wildcard https: for scripts and connections. If you need stricter rules, add your specific Umami host URL.

Works locally but not in production — Check that environment variables are set in your deployment platform and that the production server can reach the Umami host.

Previous ← Profile & DashboardNextComponents & Composables →