Storybook Addon Matomo

Note

This is a fork maintained by the community to provide support for Storybook 9 and beyond. This addon was originally developed by Alex Nicholls.

---

Storybook Addon Matomo can be used to support Matomo Analytics in Storybook.

Getting Started

Install:

yarn add -D storybook-addon-matomo

npm install -D storybook-addon-matomo

pnpm install -D storybook-addon-matomo

In your .storybook/main.ts file, add the following:

// .storybook/main.ts
export default {
  addons: ['storybook-addon-matomo'],
}

In your .storybook/manager.ts file, add the following config, and adjust values to match your Matomo settings:

// .storybook/manager.ts
import { addons } from 'storybook/manager-api'

addons.setConfig({
  matomo: {
    baseUrl: 'https://your.matomo-instance.com/',
    siteId: 123456,
  },
})

If you would like to store your baseUrl or siteId, etc. in an environment variable so it is not available in your repo, add an .env file to the root of your project or set environment variables in your CI:

STORYBOOK_MATOMO_URL = https://LINK.TO.DOMAIN
STORYBOOK_MATOMO_SITE_ID = 3

And reference those variables in .storybook/manager.ts:

// .storybook/manager.ts
import { addons } from 'storybook/manager-api'

addons.setConfig({
  matomo: {
    baseUrl: process.env.STORYBOOK_MATOMO_URL,
    siteId: process.env.STORYBOOK_MATOMO_SITE_ID,
  },
})

Options

To enable Matomo's heartbeat timer that more accurately tracks time spent on a page, pass heartbeat: true to the config:

// .storybook/manager.ts
addons.setConfig({
  matomo: {
    // ...
    heartbeat: true,
  },
})

Contributing

Code of Conduct

Please read the Code of Conduct first.

Developer Certificate of Origin

To ensure that contributors are legally allowed to share the content they contribute under the license terms of this project, contributors must adhere to the Developer Certificate of Origin (DCO). All contributions made must be signed to satisfy the DCO. This is handled by a Pull Request check.

By signing your commits, you attest to the following:

1. The contribution was created in whole or in part by you and you have the right to submit it under the open source license indicated in the file; or
2. The contribution is based upon previous work that, to the best of your knowledge, is covered under an appropriate open source license and you have the right under that license to submit that work with modifications, whether created in whole or in part by you, under the same open source license (unless you are permitted to submit under a different license), as indicated in the file; or
3. The contribution was provided directly to you by some other person who certified 1., 2. or 3. and you have not modified it.
4. You understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information you submit with it, including your sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

Getting Started

This project uses PNPM as a package manager.

• See the installation instructions for PNPM
• Run pnpm i

Useful commands

• pnpm start starts the local Storybook
• pnpm build builds and packages the addon code
• pnpm pack:local makes a local tarball to be used as a NPM dependency elsewhere
• pnpm test runs unit tests

Migrating to a later Storybook version

If you want to migrate the addon to support the latest version of Storyboook, you can check out the addon migration guide.

Release System

This package auto-releases on pushes to main with semantic-release. No changelog is maintained and the version number in package.json is not synchronised.

Support

Please open an issue for bug reports or code suggestions. Make sure to include a working Minimal Working Example for bug reports. You may use storybook.new to bootstrap a reproduction environment.