nuxt-umami
v2.6.1
Published
Integrate Umami Analytics into Nuxt
Downloads
6,292
Maintainers
Readme
Nuxt Umami
Integrate Umami Analytics into your Nuxt websites / applications.
Features
- 📖 Open Source
- ✨ SSR Support, of course
- ➖ No extra script, no loading delay
- 😜 Escapes ad & script blockers
- 💯 Simple, feature complete, extensive config
- ✅ Typescript, JSDocs, auto completion
- ✅ Auto imported, available (almsot) everywhere
- ✅ Easy debuggin' (one
console.log
at a time)
[!IMPORTANT] Nuxt Umami v2 uses features that are only available in Nuxt 3 (Nuxt Layers). Check out Nuxt Umami v1 for Nuxt 2 compat.
Setup
🚀 Try it online
Step 1: Install and add to Nuxt
Install using your favorite package manager...
pnpm add nuxt-umami #pnpm
npm install nuxt-umami #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']
});
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'],
appConfig: {
umami: {
// ...umami config here
},
},
});
Environment Variables
[!NOTE] Available in
^2.1.0
and takes precedence overappConfig
.
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:
<script setup>
function complexCalc() {
// ... do something
umTrackEvent('complex-btn', { propA: 1, propB: 'two', propC: false });
}
</script>
<template>
<button @click="umTrackEvent('button-1')">
Button 1
</button>
<button @click="complexCalc">
Button 2
</button>
</template>
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
|
| 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
|
| version | 1 \| 2
| Umami version | no | 1
|
| useDirective | boolean
| Option to enable the v-umami
directive. See below. | no | false
|
| debug | boolean
| Option to enable error logs (in production), useful for testing in prod :) | no | false
|
Usage
Two functions are auto-imported, umTrackView()
and umTrackEvent()
. Use them however and wherever you like. These functions work even in <script setup>
without the onMounted
hook. The v-umami
directive can be enabled in the config.
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
or theref
search param in the url (eg:example.com/?ref=thereferrer
).
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.
Method Return
Both umTrackEvent
and umTrackView
return a Promise with an ok
status that you can await or chain, Promise<{ok: boolean}>
.
umTrackView().then(res => console.log(res.ok));
umTrackView().then(({ ok }) => console.log(ok));
Vue Directive
[!NOTE] Available from
^2.5.0
. AdduseDirective: true
to your config.
You can pass a string as the event name, or an object containing a name
property (required, this is the event name). Every other property will be passed on as event data.
<button v-umami="'Event-Name'">
Event Button
</button>
<button v-umami="{name: 'Event-Name'}">
as object
</button>
<button v-umami="{name: 'Event-Name', position: 'left', ...others}">
with event details
</button>
FAQS and Quirks
- I don't see errors in live sites...
- If you're debugging live sites, set
debug: true
in your config.
- If you're debugging live sites, set
- Can I use Umami v2/Cloud?
- Yes. To use Umami v2, set
version: 2
in the Nuxt-Umami config.
- Yes. To use Umami v2, set
nuxt typecheck
fails! What can I do to resolve it?- The problem could be tied to
pnpm
's dependency hoisting. Thanks to Jeet for discovering this. Simply create a.npmrc
file in the root of your Nuxt project and addshamefully-hoist=true
. If that doesn't work, I'll be happy to look further into it.
- The problem could be tied to
- Welp, I am getting some CORS errors!
- Some adblockers like uBlock and Ghostery block Umami Cloud's endpoints. Try to disable your adblockers (yes, all of them). Also, double-check your config and Umami version. If all else fails, host your own Umami instance.
- How do I set up my own Umami instance?
- Miracle Onyenma published a simple guide in his blog. Check it out.
- Should I sponsor this project?
- Absolutely, you can do that here: https://github.com/sponsors/ijkml.
Issues, Bugs, Ideas?
Contributions are welcome, start a discussion, send a PR! If you find an issue, keep it, finders keepers 😅. (Or, open an issue, I'll be happy to help.)
Contributors
Thank you!