nuxt-umami

Nuxt Umami ^@next

Integrate Umami Analytics into your Nuxt websites / applications.

Heads up: This version uses features (Nuxt Layers) that are only available in Nuxt 3. Check out Nuxt Umami v1 for Nuxt 2 compat.

Features

• 📖 Open Source
• ✨ SSR Support, of course
• ➖ No extra script: no extra tag, no script loading, instant availability
• 😜 Escapes ad & script blockers (catch me if you can)
• 💯 Simplified usage, feature complete, extensive config
• ✅ Better Typescript, JSDocs, auto completion
• ✅ Error handling + debugging
• ✅ Nuxt utils + auto import

Setup

🚀 Try it online

Step 1: Install and add to Nuxt

Install using your favorite package manager...

pnpm add nuxt-umami@next #pnpm

npm install nuxt-umami@next #npm

Then add nuxt-umami to your extends array in nuxt.config:

defineNuxtConfig({
  extends: ['nuxt-umami']
});

Or, you can totally skip the installation process and do

defineNuxtConfig({
  extends: ['github:ijkml/nuxt-umami#next']
});

Warning: This might cause unwanted errors due to changes as the branch is still WIP.

Step 2: Configure Umami

You can provide configuration options using the app.config.ts file or appConfig property of the Nuxt config.

app.config.ts file

(recommended for readability and ease of update)

export default defineAppConfig({
  umami: {
  // ...umami config here
  },
});

appConfig property

defineNuxtConfig({
  extends: ['nuxt-umami@next'],
  appConfig: {
    umami: {
      // ...umami config here
    },
  },
});

Environment Variables

Note: Available in ^2.1.0 and takes precedence over appConfig.

You can provide the host and id config (only) as environment variables. Simply add NUXT_PUBLIC_UMAMI_HOST and NUXT_PUBLIC_UMAMI_ID to your .env file, and that's it.

NUXT_PUBLIC_UMAMI_HOST="https://domain.tld"
NUXT_PUBLIC_UMAMI_ID="abc123-456def-ghi789"

Step 3:

Use it.

Configuration

option	type	description	required	default
host	string	Your Umami endpoint. This is where your script is hosted. Eg: https://ijkml.xyz/.	yes	''
id	string	Unique website-id provided by Umami.	yes	''
domains	string | Array<string>	Limit tracker to specific domains by providing an array or comma-separated list (without 'http'). Leave blank for all domains.	no	undefined
ignoreDnt	boolean	Option to ignore browsers' Do Not Track setting.	no	true
autoTrack	boolean	Option to automatically track page views.	no	true
ignoreLocalhost	boolean	Option to prevent tracking on localhost.	no	false
customEndpoint	string	Set a custom COLLECT_API_ENDPOINT. See Docs.	no	undefined

Usage

Two functions are auto-imported, umTrackView() and umTrackEvent(). Use them however and wherever you like.

Available Methods

• umTrackView(url, referrer)

  • url: the path being tracked, eg /about, /contact?by=phone#office. This can be correctly inferred. Equivalent of router.fullPath.
  • referrer: the page referrer. This can be correctly inferred. Equivalent of document.referrer.

• umTrackEvent(eventName, eventData)

  • eventName: a string type text
  • eventData: an object in the format {key: value}, where key is a string and value is a string, number, or boolean.

Reference: Umami Tracker Functions.

Umami Cloud, v2

Umami v2's release is on the horizon, and they currently offer a free beta plan for Umami Cloud. To use v2 (or Cloud), set version: 2 in the Umami config.

Nuxt Umami v2 is not compatible with Umami (v2) Cloud. You can try Nuxt Umami v1.

Note: At this point, I do not have any plans to support Umami v2 Cloud (not until the official release and the new docs at least). But if you want to help, reach out.

Issues, Bugs, Ideas?

Open an issue. Contributions are welcome, just send a PR! If you encounter any issues, don't hesitate to open an issue. I'm always available to help and resolve any bugs.

Contributors

---

MIT License © 2023 ML