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

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: "[email protected]" });

// 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