Deploy Umami analytics avoiding data loss, tracking failures, and integration issues.
Scanned 9/6/2026
Install to Claude Code
Skills Directorynpx -y skills add clawic/skills --skill umami --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Umami?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/clawic-umami)More formats (shields.io, HTML) on the badges page.
---
name: Umami
slug: umami
version: 1.0.0
description: Deploy Umami analytics avoiding data loss, tracking failures, and integration issues.
homepage: https://clawic.com/skills/umami
metadata:
clawdbot:
emoji: 📊
os:
- linux
- darwin
- win32
displayName: Umami
---
## Critical Configuration
- `HASH_SALT` must never change — changing it invalidates all existing data, essentially a reset
- SQLite is not supported — despite being Node.js, Umami requires PostgreSQL or MySQL
- Database contains everything — all tracking data, config, users; backup only this
## Tracking Script Traps
- `data-website-id` must match Umami config exactly — wrong ID = zero data, no error shown
- Script blocked by ad blockers — self-host on same domain as site to avoid blocking
- Single Page Apps don't auto-track navigation — must call `umami.track()` on route changes
- Script in `<head>` not `<body>` — late loading misses initial pageview
## SPA Integration
- React: call `umami.track('pageview')` in router effect or navigation handler
- Next.js: use `@umami/next` package — handles app router and pages router
- Vue/Nuxt: router afterEach hook with `umami.track()`
- Check `window.umami` exists before calling — script may load after component mounts
## Custom Events
- Event names appear verbatim in dashboard — use consistent naming scheme
- Properties only searchable via API — not visible in default dashboard
- `umami.track('event', { key: 'value' })` for properties
## Self-Hosting Considerations
- Low resources needed — 256MB RAM handles most sites
- PostgreSQL needs more resources than Umami itself — plan accordingly
- Reverse proxy required for HTTPS — Umami runs HTTP on port 3000
- Backup strategy = database backup — no filesystem state to worry about
## Multi-Site Setup
- One Umami instance handles many sites — add in Dashboard > Settings > Websites
- Each site needs unique tracking script — get from Websites settings
- Share button available per site — generates public dashboard URL
## Troubleshooting
- Zero pageviews — check browser Network tab, verify script loads without error
- Script 404 — verify CORS headers if cross-domain, or self-host on same domain
- Events not appearing — check browser console for `umami` errors
- Dashboard slow — check database performance, PostgreSQL query times
## Common Mistakes
- Using same website ID for dev and prod — pollutes analytics with test data
- Not testing script after deploy — CDN caching or minification can break it
- Expecting real-time updates — dashboard has slight delay, not instant
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
