How to track analytics on a Docusaurus-built website?

[RemiLacroix-IDRIS]

Hi,

What would you suggest to keep track of a Docusaurus-built website usage?

Being that Docusaurus generate a client app, I think that using the server logs wouldn't work as it would miss most of the page views.

We would rather use something self-hosted and simple.

Best,
Rémi

[slorber]

You can take inspiration from existing analytics plugin we provide, based on client module lifecycle hooks:

• https://docusaurus.io/docs/advanced/client#client-module-lifecycles
• https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-plugin-google-gtag
• https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-plugin-vercel-analytics

There are many community plugins available, implemented in similar ways, for example: https://posthog.com/docs/libraries/docusaurus

You have to track the navigations using client-side code

[amasen02]

For a self-hosted, lightweight, and privacy-respecting analytics solution on Docusaurus, here are the two best options, along with how to handle Single-Page Application (SPA) pageview tracking:

---

Option 1: Umami (Recommended for Self-Hosting)

Umami is completely open-source, GDPR-compliant, cookie-less, and runs easily via a tiny Docker container with Postgres or MySQL.

Why it fits Docusaurus:

Umami's tracking script automatically patches history.pushState in the browser, meaning it tracks client-side SPA navigation in Docusaurus out of the box without needing a custom plugin.

How to install in docusaurus.config.js:

Add the tracking script directly to the scripts array:

// docusaurus.config.js
module.exports = {
  // ...
  scripts: [
    {
      src: 'https://analytics.your-domain.com/script.js',
      defer: true,
      'data-website-id': 'YOUR-UMAMI-WEBSITE-ID',
    },
  ],
};

---

Option 2: Plausible Community Edition (Self-Hosted)

Plausible CE is another popular self-hosted option. Like Umami, it automatically tracks HTML5 History API route changes.

// docusaurus.config.js
module.exports = {
  // ...
  scripts: [
    {
      src: 'https://plausible.your-domain.com/js/script.js',
      defer: true,
      'data-domain': 'your-docs-domain.com',
    },
  ],
};

---

Option 3: Custom In-House Endpoint via Docusaurus Client Module

If you already have a simple custom backend endpoint (e.g. FastAPI / Express / Go) logging events to SQLite/Postgres, you can hook into Docusaurus's lifecycle events directly using a client module:

1. Create src/clientModules/analytics.js:

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

export function onRouteDidUpdate({ location, previousLocation }) {
  if (
    ExecutionEnvironment.canUseDOM &&
    location.pathname !== previousLocation?.pathname
  ) {
    // Send lightweight beacon on each route transition
    navigator.sendBeacon?.(
      'https://api.your-domain.com/track',
      JSON.stringify({
        path: location.pathname,
        referrer: document.referrer,
        ts: Date.now(),
      })
    );
  }
}

2. Register it in docusaurus.config.js:

// docusaurus.config.js
module.exports = {
  // ...
  clientModules: [
    require.resolve('./src/clientModules/analytics.js'),
  ],
};

Recommendation:

If you want something ready-made with a clean dashboard and zero client-side configuration, Umami via Docker + scripts in docusaurus.config.js is by far the simplest and cleanest path.