📦 docusaurus-plugin-umami

Umami Analytics plugin for Docusaurus.

⚠️ production only

This plugin is always inactive in development and only active in production to avoid polluting the analytics statistics.

Installation

Install the plugin with npm:

npm install --save @dipakparmar/docusaurus-plugin-umami

or with yarn:

yarn add @dipakparmar/docusaurus-plugin-umami

or with pnpm:

pnpm install @dipakparmar/docusaurus-plugin-umami

or with bun:

bun install @dipakparmar/docusaurus-plugin-umami

Configuration

Add the plugin and websiteID and analyticsDomain to your docusaurus.config.js:

module.exports = {
  plugins: [
    [
      "@dipakparmar/docusaurus-plugin-umami",
      /** @type {import('@dipakparmar/docusaurus-plugin-umami').Options} */
      ({
        websiteID: "your-website-id", // Required
        analyticsDomain: "analytics.mydomain.com", // Required
        scriptName: "script.js", // Optional, defaults to script.js
        dataHostURL: "", // Optional
        dataAutoTrack: true, // Optional, defaults to true
        dataDoNotTrack: false, // Optional, defaults to false
        dataCache: false, // Optional, defaults to false
        dataDomains: "", // Optional, comma separated list of domains, *Recommended*
        dataExcludeSearch: false, // Optional, defaults to false
        dataExcludeHash: false, // Optional, defaults to false
        dataTag: "", // Optional
        dataBeforeSend: "beforeSendHandler", // Optional
        enableRecorder: false, // Optional, defaults to false. Loads recorder.js for session replays & heatmaps
      }),
    ],
  ],
};

Options

Accepted fields:

Name	Type	Default	Description
websiteID	string	Required	The unique website ID from your Umami Analytics.
analyticsDomain	string	Required	Your domain of where Umami Analytics is hosted.
scriptName	string	script.js	Name of your custom tracker script.
dataHostURL	string		By default, Umami will send data to wherever the script is located. You can override this to send data to another location.
dataAutoTrack	boolean	true	By default, Umami tracks all pageviews and events for you automatically. You can disable this behavior and track events yourself using the tracker functions.
dataDoNotTrack	boolean	false	Configure Umami to respect the visitor's Do Not Track setting.
dataCache	boolean	false	If you get a lot of pageviews from the same user, for example in a forum website, you can cache some data to improve the performance of the tracking script.
dataDomains	string		If you want the tracker to only run on specific domains, you can add them to your tracker script. This is a comma delimited list of domain names. Helps if you are working in a staging/development environment.
dataExcludeSearch	boolean	false	Configure the tracker to not record query parameters in the URL.
dataExcludeHash	boolean	false	Configure the tracker to not record URL hashes.
dataTag	string		Add a tag to your website's data for segmentation (e.g. A/B testing).
dataBeforeSend	string		Define a function that will be called before sending the data. Useful for modifying the data before it's sent to the server.
enableRecorder	boolean	false	Load Umami's recorder.js script to enable session replays and heatmaps. Which of the two is recorded is toggled per-website in the Umami dashboard.
autoIdentify	boolean	false	Assign a stable anonymous ID (persisted in localStorage) so a visitor's sessions are grouped via distinct IDs. See the privacy note below. Honors Do Not Track / Global Privacy Control.
autoIdentifyStorageKey	string	umami.anonymous-id	localStorage key used to persist the autoIdentify anonymous ID.

Custom event tracking

Once the tracker is loaded you can record custom events two ways.

Data attributes (no JS)

Add data-umami-event (and optional data-umami-event-*) to any element:

<button data-umami-event="Signup" data-umami-event-plan="pro">
  Sign up
</button>

Typed client helpers

Import from the /client entry for a safe, typed API. The helpers no-op during SSR and before the deferred tracker script has loaded, so they are safe to call anywhere:

import {
  track,
  identify,
  useUmami,
} from "@dipakparmar/docusaurus-plugin-umami/client";

// Fire a custom event
track("Signup", { plan: "pro" });

// Assign a distinct id to the session — https://docs.umami.is/docs/distinct-ids
identify({ id: "user@example.com" });

// Inside a React component
function SignupButton() {
  const { track } = useUmami();
  return <button onClick={() => track("Signup", { plan: "pro" })}>Sign up</button>;
}

Both approaches work inside .mdx docs — data-umami-event attributes pass through, and you can import the helpers at the top of the file. Because the helpers no-op during server-side rendering, they are safe to call while Docusaurus prerenders your pages (useUmami() is a hook, so call it at the top of the MDX doc or inside a component, not conditionally).

Tags are set via the dataTag option (the data-tag script attribute), not the tracking API — see Umami tags.

Anonymous session grouping (autoIdentify)

Set autoIdentify: true to have the plugin generate a random ID on the first visit, persist it in localStorage, and identify() it on every load — so a visitor's sessions are grouped together (same browser = same ID). It's opt-in and honors Do Not Track / Global Privacy Control.

⚠️ Privacy. A persistent identifier is personal data under GDPR / ePrivacy and generally requires user consent — enabling this negates Umami's default cookieless, consent-free posture. Using localStorage instead of a cookie does not change this; the legal treatment is the same. You are responsible for obtaining consent where required.

For a consent-gated approach, leave autoIdentify off and call identify() from the /client entry yourself, after your own consent flow.

Reference:

• Docusuarus Plugin Readme Example from https://github.com/sgromkov/docusaurus-plugin-yandex-metrica
• Plugin Architecture: https://docusaurus.io/docs/api/plugin-methods#example
• Umami Analytics Tracker Configuration: https://umami.is/docs/tracker-configuration