Embed the Umami analytics library into Nuxt

Nuxt Umami


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.


  • 📖 Open Source
  • ✨ SSR Support, of course
  • ➖ No extra script: no loading delay, instant availability
  • 😜 Escapes most ad & script blockers (catch me if you can)
  • 💯 Simple, feature complete, extensive config
  • ✅ Typescript, JSDocs, auto completion
  • ✅ Easy debuggin' (one console.log at a time)
  • ✅ Auto imported, available (almsot) everywhere


🚀 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:

  extends: ['nuxt-umami']

Or, you can totally skip the installation process and do

  extends: ['github:ijkml/nuxt-umami']

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

  extends: ['nuxt-umami'],
  appConfig: {
    umami: {
      // ...umami config here

Environment Variables

Note: Available in ^2.1.0 and takes precedence over appConfig.

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.


Step 3:

Use it

<script setup>
function complexCalc() {
  // ... do something
  umTrackEvent('complex-btn', { propA: 1, propB: 'two', propC: false });

  <button @click="umTrackEvent('button-1')">Button 1</button>

  <button @click="complexCalc">Button 2</button>


hoststringYour Umami endpoint. This is where your script is hosted. Eg:''
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
ignoreDntbooleanOption to ignore browsers' Do Not Track setting.notrue
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


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

Vue Directive

Note: Available from ^2.5.0. 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>


For cases where you need that console.log('here') in live sites, set debug: true in your config.

Umami v2

Note: Support for Umami v2 is available in 2.3.0 and later.

To use Umami v2, set version: 2 in the Umami config.

Setup guide

Learn how to host your own Umami instance and set up your Nuxt app using Miracle Onyenma's simple guide.

Issues, Bugs, Ideas?

Open an issue. Contributions are welcome, just send a PR! If you encounter any issues, don't hesitate to open an issue. I'm always available to help and resolve any bugs.


Nuxt Umami contributors

MIT License © 2023 ML