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,
    // tag: 'website-variation-123',
  },
});

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.

Provided env variables will override the base config in nuxt.config.ts.

If you are upgrading from v2, rest assured v3 will also pick up NUXT_PUBLIC_UMAMI_HOST and NUXT_PUBLIC_UMAMI_ID.

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.

Read more at Umami Docs - Environment Variables

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 below).

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.

tagstring | null

Use Umami Tag (see docs below)

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';
  tag: string | null;
}>;

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.

Umami Tag

From the official docs, you can use Umami Tags for

A/B Testing: Test different versions of a webpage or campaign to see which performs better.
Group events to allow filtering and insights under a single website overview.