Configuration

Configure Nuxt Umami to work with your app.

Add umami to your Nuxt config.

nuxt.config.ts 
export default defineNuxtConfig({
  modules: ['nuxt-umami'],

  umami: {
    id: 'my-w3b517e-id',
    host: 'https://my-umami.xyz',
    autoTrack: true,
    // proxy: 'cloak',
    // useDirective: true,
    // ignoreLocalhost: true,
    // excludeQueryParams: false,
    // domains: ['cool-site.app', 'my-space.site'],
    // customEndpoint: '/my-custom-endpoint',
    // enabled: false,
    // logErrors: true,
  },
});

Finding Config Options

Screenshot of Umami Cloud showing a website's tracking code.

Config options host and id can be extracted from the tracking code Umami provides. src and data-website-id in the <script> tag map to host and id respectively.

This is the case for both Umami Cloud and self-hosted instances.

Diagram showing how Umami script attributes src and data-website-id map to nuxt-umami config options host and id.

Environment Variables

You can provide the host and id as env variables. Simply add NUXT_UMAMI_HOST and NUXT_UMAMI_ID to your .env file.

Config Options

Options

enabledboolean
true
Whether to enable the module.
hostrequiredstring
Your umami endpoint. This is where you would normally load the script from.
  • Example: 'https://ijkml.xyz/'.
idrequiredstring
Unique identifier provided by Umami.
  • Example: '3c255b6d-678a-42dd-8074-272ee5b78484'.
domainsstring[]
undefined
Configure the tracker to only run on specific domains. Provide a list of domains (without 'http'). Leave undefined to run on all domains.
  • Example: ['mywebsite.com', 'mywebsite2.com'].
autoTrackboolean
true
Automatically track page views.
ignoreLocalhostboolean
false
Whether or not to track during development (localhost).
customEndpointstring
Self-hosted Umami lets you set a COLLECT_API_ENDPOINT, which is:
  • /api/collect by default in Umami v1.
  • /api/send by default in Umami v2.
excludeQueryParamsboolean
false
Exclude query/search params from tracked URLs.
  • false => /page/link?search=product-abc&filter=asc.
  • true => /page/link.
useDirectiveboolean
false
Enable v-umami directive.
logErrorsboolean
false
Enable warning and error logs in production.
proxyfalse | 'direct' | 'cloak'
false
API proxy mode (see docs).
trailingSlash'any' | 'always' | 'never'
'any'
Enforce consistent trailing slash in tracked pages.
  • any => default option, leave as is.
  • always => always include trailing slash.
  • never => always remove trailing slash.

Type

types.d.ts 
type Options = Partial<{
  enabled: boolean;
  host: string;
  id: string;
  domains: string | string[] | null;
  autoTrack: boolean;
  ignoreLocalhost: boolean;
  customEndpoint: string | null;
  excludeQueryParams: boolean;
  useDirective: boolean;
  logErrors: boolean;
  proxy: false | 'direct' | 'cloak';
  trailingSlash: 'any' | 'always' | 'never';
}>;

Proxy Mode

Nuxt Umami can leverage Nitro route rules and Nuxt server endpoints to proxy requests to your Umami endpoint.

There are currently 3 proxy options:

  • false: Requests go directly to your Umami endpoint.
  • direct: Simple proxy using route rules.
  • cloak: Proxy with "sensitive" data kept out of your client bundle.

With cloak, your website id and host are only available server-side unlike direct or none.

Installation
How to install Nuxt Umami in your app.
Usage
Using Umami tracking functions and directive.