umami

Go to documentation

Embed the Umami analytics library into Nuxt

1 maintainer

970 installs

42 stars

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

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`
version	`1 \| 2`	Umami version (Cloud)	no	`1`

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.