👨‍🏫 The Mastering Nuxt 3 course is now completed!

Discover the course
umami

Embed the Umami analytics library into Nuxt

Nuxt Umami @next

npmDownloadsLicense

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

Open in StackBlitz

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
},
},
});

Step 3:

Use it.

Configuration

optiontypedescriptionrequireddefault
hoststringYour Umami endpoint. This is where your script is hosted. Eg: https://ijkml.xyz/.yes''
idstringUnique website-id provided by Umami.yes''
domainsstring | Array<string>Limit tracker to specific domains by providing an array or comma-separated list (without 'http'). Leave blank for all domains.noundefined
ignoreDntbooleanOption to ignore browsers' Do Not Track setting.notrue
autoTrackbooleanOption to automatically track page views.notrue
ignoreLocalhostbooleanOption to prevent tracking on localhost.nofalse
version1 | 2Umami version (Cloud)no1

Environment Variables

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

You can provide the host and id config 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"

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.

Warning: v2 is still WIP pending official release and the new docs. Test rigorously, and if you encounter bugs/issues, please open an issue.

Issues, Bugs, Ideas?

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

Contributors

Nuxt Umami contributors

MIT License © 2023 ML