Backstage Analytics Module: Matomo Analytics Plugin

The Matomo Analytics Module gives Backstage a direct bridge to Matomo. It implements the Backstage Analytics API and forwards events to your Matomo instance as people browse and use your developer portal. It fits with the built in analytics system, so your existing event hooks and page views flow through without extra glue work. You keep your Backstage code focused on features while Matomo collects the signals.

At a high level the plugin tracks page views and user actions across core pages and custom plugins. You can see which areas get traffic, which routes people follow, and which features need attention. This helps with questions like which plugins are adopted, which docs are ignored, and which paths lead to dead ends. Use these insights to plan improvements, clean up unused pieces, and measure the impact of releases over time.

Matomo itself is open source and can run on your own infrastructure. Many teams prefer it when they want control of analytics data and fewer third party dependencies. Pairing Backstage with Matomo makes it easier to meet privacy needs while still getting clear usage metrics from your portal. If your company already uses Matomo for product sites, this module lets you apply the same reporting model to your internal tools.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Step 1 Install the package

Copy

# from your Backstage root directory
yarn workspace app add @backstage-community/plugin-analytics-module-matomo

Step 2 Wire it in a new frontend system

If your app uses the new frontend system, add the module to the features list when you create the app.

Copy

// packages/app/src/App.tsx or packages/app/src/app.tsx
import { createApp } from '@backstage/frontend-app-api';
import matomoModule from '@backstage-community/plugin-analytics-module-matomo/alpha';

const app = createApp({
  features: [matomoModule],
});

export default app;

There is no page to add. The module hooks into the analytics API and sends events in the background.

Step 3 Wire it in a classic frontend system

If your app uses the classic system, register the API implementation in apis ts.

Copy

// packages/app/src/apis.ts
import {
  AnyApiFactory,
  analyticsApiRef,
  configApiRef,
  createApiFactory,
  identityApiRef,
} from '@backstage/core-plugin-api';

import { MatomoAnalytics } from '@backstage-community/plugin-analytics-module-matomo';

export const apis: AnyApiFactory[] = [
  // Instantiate and register the Matomo Analytics API implementation
  createApiFactory({
    api: analyticsApiRef,
    deps: { configApi: configApiRef },
    factory: ({ configApi }) => MatomoAnalytics.fromConfig(configApi),
  }),
];

There is no page to add. The module runs without a visible component.

Step 4 Configure app config

Add the minimal config to app config yaml. Use your Matomo host and site id.

Copy

# app-config.yaml
app:
  analytics:
    matomo:
      host: ${ANALYTICS_MATOMO_INSTANCE_URL}
      siteId: ${ANALYTICS_MATOMO_SITE_ID}
      identity: optional # optional to enable user tracking. Disabled by default
      sendPlainUserId: optional # optional to not hash user id when user tracking is enabled

You can set these values with environment variables or inline values.

Step 5 Update content security policy optional

Allow scripts from your Matomo host.

Copy

# app-config.yaml
backend:
  csp:
    connect-src: ["'self'", 'http:', 'https:']
    # add this line below
    script-src: ["'self'", "'unsafe-eval'", '${ANALYTICS_MATOMO_INSTANCE_URL}']

Step 6 Backend install

No backend package is needed. This module only implements the frontend analytics API. Nothing to install for the new backend system or the old backend system.

Changelog

This changelog is produced from commits made to the Matomo Analytics plugin since 6 months ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Features

Add NFS support for Matomo through the New Frontend System blueprint. This lets you run multiple analytics implementations side by side without extra app code. #5284 merged 3 days ago
Add optional config to disable encryption of userId when user tracking is on. #4301 merged 3 months ago

Set up Backstage in minutes with Roadie

Focus on using Backstage, rather than building and maintaining it.

Get a demo