umami
Go to documentationEmbed the Umami analytics library into Nuxt
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 overappConfig
.
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 ofrouter.fullPath
.referrer
: the page referrer. This can be correctly inferred. Equivalent ofdocument.referrer
.
umTrackEvent(eventName, eventData)
eventName
: a string type texteventData
: an object in the format{key: value}
, wherekey
is a string andvalue
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.