nuxt-umami

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)

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

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. Please note that provided env variables override appConfig.

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

Step 3:

Use it

<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 freely. Please note that in <script setup>, these functions might fail silently. Use the onMounted hook or call them on user interaction.

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 of router.fullPath.
  • referrer: the page referrer. This can be correctly inferred. Equivalent of document.referrer or the ref search param in the url (eg: example.com/?ref=thereferrer).

• 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.

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

To use directive v-umami, add useDirective: 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>

Prevent tracking yourself

To prevent tracking yourself, add the key umami.disabled to your browser's localStorage. Set the value to 1.

See: Umami Docs.

FAQS and Quirks

• I don't see errors in live sites...
  • If you're debugging live sites, set debug: true in your config.
• Can I use Umami v2/Cloud?
  • Yes. To use Umami v2, set version: 2 in the Nuxt-Umami config.
• 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 add shamefully-hoist=true. If that doesn't work, I'll be happy to look into it further.
• 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.
• autoTrack is not working?
  • The current implementation of autoTrack relies on <NuxtPage> being present in your app. If you don't have <NuxtPage>, you'd have to call umTrackView() yourself onMounted(). See this issue.
• 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!

---

MIT License © 2023 ML