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,
    // enabled: false,
    // useDirective: true,
    // ignoreLocalhost: true,
    // domains: ['cool-site.app', 'my-space.site'],
    // urlOptions: {
    //   trailingSlash: 'always',
    //   excludeSearch: false,
    //   excludeHash: false,
    // },
    // proxy: 'cloak',
    // logErrors: true,
    // customEndpoint: '/my-custom-endpoint',
    // 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.

Config 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.
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).
tagstring | null
Use Umami Tag (see docs below).
urlOptionsobject
Configure how URLs are handled.
trailingSlash'always' | 'never' | 'any'
'any'
Enforce consistent trailing slash in tracked pages.
  • always => always include trailing slash.
  • never => always remove trailing slash.
  • any => default option.
excludeSearchboolean
false
Exclude query/search params from tracked URLs.
  • false => /page/link?search=product-abc&filter=asc.
  • true => /page/link.
excludeHashboolean
false
Exclude hash params from tracked URLs.
  • false => /page/link#contact.
  • true => /page/link.
trailingSlash
Deprecated. Use urlOptions.trailingSlash instead.
excludeQueryParams
Deprecated. Use urlOptions.excludeSearch instead.

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.

Nuxt Umami provides 3 ways to set tags. Whichever method you choose is entirely up to you and your use case (from lowest to highest priority):

  • directly in nuxt.config.ts
    nuxt.config.ts
    export default defineNuxtConfig({
  umami: {
    ...others,
    tag: 'design-g7'
  },
});
  • env variable NUXT_UMAMI_TAG
    .env
    NUXT_UMAMI_TAG="variation-25"
  • umami.tag client-side in localStorage.

Config Type

options
type ModuleOptions = Partial<{
  /**
   * Whether to enable the module
   *
   * @default true
   */
  enabled: boolean;
  /**
   * Your umami endpoint. This is where you would
   * normally load the script from.
   *
   * @required true
   * @example 'https://ijkml.xyz/'
   * @see [How to find?](https://umami.nuxt.dev/api/configuration#finding-config-options).
   */
  host: string;
  /**
   * Unique identifier provided by Umami
   *
   * @required true
   * @example `3c255b6d-678a-42dd-8074-272ee5b78484`
   */
  id: string;
  /**
   * Configure the tracker to only run on specific domains.
   * Provide an array or comma delimited list of domains (without 'http').
   * Leave as `undefined` to run on all domains.
   *
   * @example 'mywebsite.com, mywebsite2.com'
   * @example ['mywebsite.com', 'mywebsite2.com']
   * @default undefined
   */
  domains: string[] | null;
  /**
   * Option to automatically track page views.
   *
   * @default true
   */
  autoTrack: boolean;
  /**
   * Whether or not to track during development (localhost).
   *
   * @default false
   */
  ignoreLocalhost: boolean;
  /**
   * 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.
   * See [Umami Docs](https://umami.is/docs/environment-variables).
   */
  customEndpoint: string | null;
  /**
   * Use Umami tags for A/B testing or to group events.
   *
   * See [Documentation](https://umami.nuxt.dev/api/configuration#umami-tag).
   */
  tag: string | null;
  /**
   * Enable `v-umami` directive
   *
   * @default false
   */
  useDirective: boolean;
  /**
   * Enable warning and error logs in production
   *
   * @default false
   */
  logErrors: boolean;
  /**
   * API proxy mode
   *
   * @see [Documentation](https://umami.nuxt.dev/api/configuration#proxy-mode).
   *
   * @default false
   */
  proxy: false | 'direct' | 'cloak';
  /**
   * Consistent trailing slash
   *
   * @default 'any'
   * @deprecated use `urlOptions` (DOCX)
   */
  trailingSlash: 'any' | 'always' | 'never';
  /**
   * Exclude query/search params from tracked urls
   *
   * false: `/page/link?search=product-abc&filter=asc`
   *
   * true: `/page/link`
   *
   * @default false
   * @deprecated use `urlOptions` (DOCX)
   */
  excludeQueryParams: boolean;
  /**
   * Configure how urls are sent to the server
   */
  urlOptions?: Partial<{
  /**
   * Enforce consistent trailing slash
   *
   * @default 'any'
   */
    trailingSlash: 'any' | 'always' | 'never';
    /**
     * Exclude query/search params from tracked urls
     *
     * false: `/page/link?search=product-abc&filter=asc`
     *
     * true: `/page/link`
     *
     * @default false
     */
    excludeSearch: boolean;
    /**
     * Exclude hash from tracked urls
     *
     * false: `/page/link#contact`
     *
     * true: `/page/link`
     *
     * @default false
     */
    excludeHash: boolean;
  }>;
}>;

export type { ModuleOptions };
Installation
How to install Nuxt Umami in your app.
Usage
Using Umami tracking functions and directive.