# Umami Setup
> Wire Umami analytics into a web app — tracker script, optional Core Web Vitals, optional session recorder — all env-var-gated so they can be flipped on/off without a code change. Use whenever the user mentions Umami, asks to add or install analytics on a self-hosted analytics backend, wants to replace Vercel Analytics / Google Analytics / Plausible, says "add Umami to this project," or pastes an Umami tracker snippet asking where it goes. Works for SvelteKit, Next.js (App and Pages routers), Nuxt, Astro, Vite + React/Vue, and plain static HTML. Also use when a user reports their Umami dashboard shows no data and asks why — this skill includes the standard debugging checklist.
- Skill: `jeffreyyvdb/umami-setup` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jeffreyyvdb/umami-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeffreyyvdb/umami-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jeffreyyvdb (https://skillmd.com/u/jeffreyyvdb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jeffreyyvdb/umami-setup
---
# Umami setup
Wires a self-hosted (or Umami Cloud) tracker into a web app in three steps:
1. **Tracker script** — emitted in the document ``, gated on two env vars.
2. **Core Web Vitals** — one `data-performance="true"` attribute on the same tag.
3. **Session recorder** (optional) — a second `
{#if umamiSrc && umamiWebsiteId}
{/if}
{#if umamiRecorderSrc && umamiWebsiteId}
{/if}
```
- SvelteKit requires the `PUBLIC_` prefix for browser-exposed env vars.
- `$env/dynamic/public` is read at runtime — flipping Umami on or off in production is an env change, not a rebuild. If the project standardises on `$env/static/public`, use that instead (build-time).
- Umami v2 auto-tracks SvelteKit client-side navigations via the History API patch. No `afterNavigate` hook needed.
## Next.js (App Router)
In `app/layout.tsx`:
```tsx
import Script from 'next/script';
const UMAMI_SRC = process.env.NEXT_PUBLIC_UMAMI_SRC;
const UMAMI_WEBSITE_ID = process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID;
const UMAMI_RECORDER_SRC = process.env.NEXT_PUBLIC_UMAMI_RECORDER_SRC;
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
{UMAMI_SRC && UMAMI_WEBSITE_ID && (
)}
{UMAMI_RECORDER_SRC && UMAMI_WEBSITE_ID && (
)}
);
}
```
- Next.js requires the `NEXT_PUBLIC_` prefix (not `PUBLIC_`). Document the mapping in `.env.example`.
- Use `next/script` with `strategy="afterInteractive"` so it doesn't block first paint.
- `NEXT_PUBLIC_*` are **inlined at build time**. Toggling Umami on or off requires a rebuild, not just an env change.
## Next.js (Pages Router)
In `pages/_document.tsx`:
```tsx
import { Html, Head, Main, NextScript } from 'next/document';
const UMAMI_SRC = process.env.NEXT_PUBLIC_UMAMI_SRC;
const UMAMI_WEBSITE_ID = process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID;
const UMAMI_RECORDER_SRC = process.env.NEXT_PUBLIC_UMAMI_RECORDER_SRC;
export default function Document() {
return (
{UMAMI_SRC && UMAMI_WEBSITE_ID && (
)}
{UMAMI_RECORDER_SRC && UMAMI_WEBSITE_ID && (
)}
);
}
```
## Nuxt 3
In `app.vue` (or a dedicated plugin), use `useHead`:
```vue
```
Expose the vars in `nuxt.config.ts`:
```ts
export default defineNuxtConfig({
runtimeConfig: {
public: {
umamiSrc: '',
umamiWebsiteId: '',
umamiRecorderSrc: '',
},
},
});
```
Env vars: `NUXT_PUBLIC_UMAMI_SRC`, `NUXT_PUBLIC_UMAMI_WEBSITE_ID`, `NUXT_PUBLIC_UMAMI_RECORDER_SRC`.
## Astro
In the shared head component (e.g. `src/components/BaseHead.astro` or `src/layouts/Layout.astro`):
```astro
---
const UMAMI_SRC = import.meta.env.PUBLIC_UMAMI_SRC;
const UMAMI_WEBSITE_ID = import.meta.env.PUBLIC_UMAMI_WEBSITE_ID;
const UMAMI_RECORDER_SRC = import.meta.env.PUBLIC_UMAMI_RECORDER_SRC;
---
{UMAMI_SRC && UMAMI_WEBSITE_ID && (
)}
{UMAMI_RECORDER_SRC && UMAMI_WEBSITE_ID && (
)}
```
`is:inline` is important — without it, Astro tries to bundle the external script and silently drops the `data-*` attributes.
## Vite + React / Vue (plain Vite, not SvelteKit / Nuxt)
Option A — edit `index.html` directly with Vite env-var substitution:
```html
```
Vite replaces `%VITE_*%` tokens at build time. Downside: if the env var is empty the tag still renders (with empty `src`) — the browser swallows it, but it's a wasted tag. For a real on/off toggle, prefer Option B.
Option B — inject from app code on mount (React example):
```tsx
import { useEffect } from 'react';
export function UmamiScripts() {
useEffect(() => {
const src = import.meta.env.VITE_UMAMI_SRC;
const websiteId = import.meta.env.VITE_UMAMI_WEBSITE_ID;
const recorderSrc = import.meta.env.VITE_UMAMI_RECORDER_SRC;
if (!src || !websiteId) return;
const make = (s: string, extra: Record = {}) => {
const el = document.createElement('script');
el.defer = true;
el.src = s;
el.dataset.websiteId = websiteId;
for (const [k, v] of Object.entries(extra)) el.dataset[k] = v;
document.head.appendChild(el);
return el;
};
const tracker = make(src, { performance: 'true' });
const recorder = recorderSrc
? make(recorderSrc, {
sampleRate: '1',
maskLevel: 'moderate',
maxDuration: '300000',
})
: null;
return () => {
tracker.remove();
recorder?.remove();
};
}, []);
return null;
}
```
Mount `` once in the root component.
## Plain static HTML
No env-var gating is possible without a build step — just edit ``:
```html
```
If the user wants conditional injection without a framework, suggest either (a) picking one of the setups above, or (b) a tiny inline `