Join the Nuxt Team at Frontend Nation 4-7 June.

umami
umami

Embed the Umami analytics library into Nuxt

Nuxt Umami

npmDownloadsLicenseSponsor

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

Open in StackBlitz

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

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
autoTrackbooleanOption to automatically track page views.notrue
ignoreLocalhostbooleanOption to prevent tracking on localhost.nofalse
customEndpointstringSet a custom COLLECT_API_ENDPOINT. See Docs.noundefined
version1 | 2Umami versionno1
useDirectivebooleanOption to enable the v-umami directive. See below.nofalse
debugbooleanOption to enable error logs (in production), useful for testing in prod :)nofalse

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?

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!

Nuxt Umami contributors

MIT License © 2023 ML