How do I install the Umami Setup skill?

Run npx skillmds@latest add jeffreyyvdb/umami-setup in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Umami Setup skill do?

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. It is listed under Web & Frontend on SkillMD.

Is Umami Setup safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Umami Setup?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Umami Setup free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Umami Setup?

jeffreyyvdb (@jeffreyyvdb) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Umami Setup by jeffreyyvdb — Agent Skill

Name: Umami Setup
Author: jeffreyyvdb

Umami setup

Wires a self-hosted (or Umami Cloud) tracker into a web app in three steps:

Tracker script — emitted in the document <head>, gated on two env vars.
Core Web Vitals — one data-performance="true" attribute on the same tag.
Session recorder (optional) — a second <script> gated on its own env var so it can be toggled without a code change.

Everything is opt-in via env vars. Unset → no scripts injected → zero network calls to Umami. This matters for CI, preview deploys, and environments where the user wants analytics off entirely.

Standard env vars

Use these names across all frameworks. For frameworks that require a prefix (Next.js → NEXT_PUBLIC_, Vite → VITE_), prepend accordingly and document the mapping in .env.example.

Var	Required?	Example
`PUBLIC_UMAMI_SRC`	yes, for tracker	`https://umami.example.com/script.js`
`PUBLIC_UMAMI_WEBSITE_ID`	yes, for tracker	`f5a2a82d-44c3-45b9-9cb6-be327bd78e86`
`PUBLIC_UMAMI_RECORDER_SRC`	no, enables recorder when set	`https://umami.example.com/recorder.js`

Critical — URL paths differ by script:

PUBLIC_UMAMI_SRC ends in /script.js (the tracker).

PUBLIC_UMAMI_RECORDER_SRC ends in /recorder.js (the session recorder).

Both must be full URLs, not the dashboard root. A common mistake is pasting https://umami.example.com/ (the dashboard) into PUBLIC_UMAMI_SRC. The browser loads the dashboard's HTML as a script, fails silently, and zero pageviews land. When the user says "I see the request go out but no data shows up in Umami," check this first.

Workflow

Detect the framework. Read package.json (look for svelte, next, nuxt, astro, vite), and scan for index.html, src/routes/+layout.svelte, app/layout.tsx, pages/_document.tsx, etc. If you can't tell, ask the user.
Open the matching section below and copy the snippet into the root document head of the app.
Update .env.example with the three vars, empty by default, with a short comment on what each does. Don't commit .env / .env.local.
Tell the user the verification steps (see § Verifying). The single most common failure is step 1's URL gotcha — call it out explicitly.

Keep the change minimal. This skill is meant to be a drop-in — resist the urge to add abstraction layers, feature flags, or helper libraries unless the user asks.

SvelteKit

Put the head snippet in the root layout — src/routes/+layout.svelte, not a nested one — so it covers every route, SSR or SPA.

<script lang="ts">
  import { env } from '$env/dynamic/public';

  const umamiSrc = env.PUBLIC_UMAMI_SRC;
  const umamiWebsiteId = env.PUBLIC_UMAMI_WEBSITE_ID;
  const umamiRecorderSrc = env.PUBLIC_UMAMI_RECORDER_SRC;
</script>

<svelte:head>
  {#if umamiSrc && umamiWebsiteId}
    <script
      defer
      src={umamiSrc}
      data-website-id={umamiWebsiteId}
      data-performance="true"
    ></script>
  {/if}
  {#if umamiRecorderSrc && umamiWebsiteId}
    <script
      defer
      src={umamiRecorderSrc}
      data-website-id={umamiWebsiteId}
      data-sample-rate="1"
      data-mask-level="moderate"
      data-max-duration="300000"
    ></script>
  {/if}
</svelte:head>

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:

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 (
    <html>
      <body>
        {children}
        {UMAMI_SRC && UMAMI_WEBSITE_ID && (
          <Script
            src={UMAMI_SRC}
            data-website-id={UMAMI_WEBSITE_ID}
            data-performance="true"
            strategy="afterInteractive"
          />
        )}
        {UMAMI_RECORDER_SRC && UMAMI_WEBSITE_ID && (
          <Script
            src={UMAMI_RECORDER_SRC}
            data-website-id={UMAMI_WEBSITE_ID}
            data-sample-rate="1"
            data-mask-level="moderate"
            data-max-duration="300000"
            strategy="afterInteractive"
          />
        )}
      </body>
    </html>
  );
}

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:

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 (
    <Html>
      <Head>
        {UMAMI_SRC && UMAMI_WEBSITE_ID && (
          <script
            defer
            src={UMAMI_SRC}
            data-website-id={UMAMI_WEBSITE_ID}
            data-performance="true"
          />
        )}
        {UMAMI_RECORDER_SRC && UMAMI_WEBSITE_ID && (
          <script
            defer
            src={UMAMI_RECORDER_SRC}
            data-website-id={UMAMI_WEBSITE_ID}
            data-sample-rate="1"
            data-mask-level="moderate"
            data-max-duration="300000"
          />
        )}
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Nuxt 3

In app.vue (or a dedicated plugin), use useHead:

<script setup lang="ts">
const config = useRuntimeConfig();
const src = config.public.umamiSrc as string | undefined;
const websiteId = config.public.umamiWebsiteId as string | undefined;
const recorderSrc = config.public.umamiRecorderSrc as string | undefined;

useHead({
  script: [
    ...(src && websiteId
      ? [{
          defer: true,
          src,
          'data-website-id': websiteId,
          'data-performance': 'true',
        }]
      : []),
    ...(recorderSrc && websiteId
      ? [{
          defer: true,
          src: recorderSrc,
          'data-website-id': websiteId,
          'data-sample-rate': '1',
          'data-mask-level': 'moderate',
          'data-max-duration': '300000',
        }]
      : []),
  ],
});
</script>

Expose the vars in nuxt.config.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):

---
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 && (
  <script
    is:inline
    defer
    src={UMAMI_SRC}
    data-website-id={UMAMI_WEBSITE_ID}
    data-performance="true"
  />
)}

{UMAMI_RECORDER_SRC && UMAMI_WEBSITE_ID && (
  <script
    is:inline
    defer
    src={UMAMI_RECORDER_SRC}
    data-website-id={UMAMI_WEBSITE_ID}
    data-sample-rate="1"
    data-mask-level="moderate"
    data-max-duration="300000"
  />
)}

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:

<!-- in <head> -->
<script defer
  src="%VITE_UMAMI_SRC%"
  data-website-id="%VITE_UMAMI_WEBSITE_ID%"
  data-performance="true"></script>

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):

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<string, string> = {}) => {
      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 <UmamiScripts /> once in the root component.

Plain static HTML

No env-var gating is possible without a build step — just edit <head>:

<script defer src="https://umami.example.com/script.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-performance="true"></script>

<!-- Optional recorder — delete to disable -->
<script defer src="https://umami.example.com/recorder.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-sample-rate="1"
  data-mask-level="moderate"
  data-max-duration="300000"></script>

If the user wants conditional injection without a framework, suggest either (a) picking one of the setups above, or (b) a tiny inline <script> that checks a server-set cookie/meta tag and injects the tracker dynamically.

`.env.example` template

Append this block:

# Umami analytics — self-hosted or Umami Cloud. Leave PUBLIC_UMAMI_SRC and
# PUBLIC_UMAMI_WEBSITE_ID unset to disable entirely. Must be the full tracker
# URL ending in /script.js, not the dashboard root.
PUBLIC_UMAMI_SRC=""
PUBLIC_UMAMI_WEBSITE_ID=""

# Optional session recorder — set to enable, unset to kill instantly.
PUBLIC_UMAMI_RECORDER_SRC=""

(Swap the prefix per framework: NEXT_PUBLIC_, NUXT_PUBLIC_, VITE_, etc.)

Verifying

After wiring the snippet, walk the user through this — most failures get caught at step 1 or 2.

Hit $PUBLIC_UMAMI_SRC in the browser. Should return JavaScript that starts with (function(){...} or similar. If it returns HTML, the URL is wrong (probably the dashboard root). Fix before going further.
Open devtools → Network, load any page of the app:
- GET to .../script.js should be 200 and served as JS.
- POST to .../api/send should fire on initial load, return 200.
- window.umami should be defined in the console.
Trigger a client-side navigation (SPA link click). A second POST to /api/send should fire. If not, the tracker isn't mounted on every route — move the snippet up to the root layout.
Dashboard check. Events take ~30 s to surface in the Umami UI. If /api/send returns 2xx but events don't appear, the data-website-id is wrong.
Disable path. Unset the env vars and reload. There should be zero Umami requests in the Network tab. Confirms the gating works for CI / preview deploys.

Gotchas

Mind the script paths. PUBLIC_UMAMI_SRC ends in /script.js (tracker), PUBLIC_UMAMI_RECORDER_SRC ends in /recorder.js (recorder). Pasting the dashboard root into either is the #1 cause of "script loads but no data appears." If the user renamed TRACKER_SCRIPT_NAME on the Umami server, adjust accordingly.
Performance (Core Web Vitals) needs Umami v3.1.0+. Older instances ignore data-performance="true" silently — no error, just no vitals data.
The recorder reuses PUBLIC_UMAMI_WEBSITE_ID — no separate ID.
Adblockers target /script.js and /api/send by default. If bypassing ad-block matters, rename the tracker on the Umami server (TRACKER_SCRIPT_NAME) and self-host under a non-umami. subdomain (stats.example.com).
SPA navigation is auto-tracked in Umami v2 via history.pushState patching. Don't reach for afterNavigate / router.afterEach / useRouter().events unless verification step 3 actually fails.
Put the script in the root layout, not a per-page head. Putting it in one page means route changes away from that page lose tracking.
Don't commit .env / .env.local. Only commit .env.example with empty values.
Respect Do Not Track. Umami does by default; if the user wants to override, that's data-do-not-track="false" on the tracker tag — but check the user actually wants this.

When the user reports "no data in Umami"

Run this triage in order — stop at the first failure:

URL gotcha. Open $PUBLIC_UMAMI_SRC in a browser. HTML response → wrong URL. Must end in /script.js.
Env vars actually set in the running environment. In Next.js remember NEXT_PUBLIC_*, not PUBLIC_*. Check Vercel/Dokploy/wherever the app is deployed.
Script tag actually in the rendered HTML. curl <app-url> | grep umami. If missing, the conditional isn't firing — check env var values.
Umami server reachable from the browser's network. Devtools Network: is /api/send returning 200? 4xx → website-id mismatch. 0 / blocked → adblocker or CORS.
Umami version. For performance data specifically, confirm the server is v3.1.0+.

Umami Setup

File contents

Umami setup

Standard env vars

Workflow

SvelteKit

Next.js (App Router)

Next.js (Pages Router)

Nuxt 3

Astro

Vite + React / Vue (plain Vite, not SvelteKit / Nuxt)

Plain static HTML

`.env.example` template

Verifying

Gotchas

When the user reports "no data in Umami"

Frequently asked questions

Umami Setup

File contents

Umami setup

Standard env vars

Workflow

SvelteKit

Next.js (App Router)

Next.js (Pages Router)

Nuxt 3

Astro

Vite + React / Vue (plain Vite, not SvelteKit / Nuxt)

Plain static HTML

.env.example template

Verifying

Gotchas

When the user reports "no data in Umami"

Related skills

Frequently asked questions

How do I install the Umami Setup skill?

What does the Umami Setup skill do?

Is Umami Setup safe to use?

Which AI agents work with Umami Setup?

Is Umami Setup free to use?

Who published Umami Setup?

`.env.example` template