@eeacms/volto-matomo
Volto add-on that integrates Matomo with Volto sites. At this moment there is a very basic integration that just pings Matomo on each router location change.
How to
To configure it, either set the following variables:
settings.matomoSiteId(if not available it uses:1)settings.matomoUrlBase(if not available it uses:https://matomo.eea.europa.eu/)
or RAZZLE_MATOMO_SITE_ID and RAZZLE_MATOMO_URL environment variables.
With version 4.0.0+, you have the possibility to use a second matomo in parallel:
settings.matomoSecondSiteId(if not available it uses:1)settings.matomoSecondUrlBase(if not available it uses:https://matomo.eea.europa.eu/)
or RAZZLE_MATOMO_SECOND_SITE_ID and RAZZLE_MATOMO_SECOND_URL environment variables.
With version 6.0.0 it is possible to have custom matomo settings based on the pathname.
settings.matomoTrackerIdFnis function with signature(pathname) => trackerId:stringsettings.matomoTrackersis a mapping oftrackerIds tomatomosetting objects (all the keys forconfig.settingscan be added to this object).
API
There are four exports in utils.js (which can be imported from volto-matomo/utils, including from other Volto addons):
trackPageView({ href, ...options }) : void- takes an object withhrefand other options and sends to Matomo a page view track;trackEvent(options) : void- takes anoptionsobject parameter and sends to Matomo an event track.trackSiteSearch(options) : void- takes anoptionsobject parameter and sends to Matomo an site search track.pushInstruction(name, null, ...args): void- takes a name and an arbitrary number of parameters, and pushes them to Matomo.
Note that the Matomo instance is behind the scenes lazy-loaded and cached.
The default behavior of volto-matomo is a call to trackPageView in utils.js, with the href and documentTitle options, on every URL change as recorded by the AppExtras component in Volto. The href is taken from props.content['@id'] received by the MatomoAppExtra.jsx component. The utils.js file exposes just a part of the Matomo React API. If you wish to extend it or to understand it better, this link might be helpful.
Upgrade
Upgrading to 8.x
This version requires
Volto 18orVolto 19and Node.js 22.
The add-on keeps the same settings shape, the same defaults and the same moment of script injection,
so a site that upgrades keeps tracking exactly as before. The release adds Volto 19 support and moves
the repository to the Volto 19 layout, where the published package lives in
packages/volto-matomo.
Breaking changes
- Node.js 22 or newer is required (
engines.node >= 22), 7.x declared no engine. - React 18 is required. The package declares
reactandreact-domas^18.2.0peers, 7.x declared no peers. - The package no longer ships the repository tooling. The Jest setup and the Docker files are gone and the unit tests moved to Vitest next to the add-on, so nothing a site imports was removed.
Requirements
Backend
Frontend
- Node.js:
>=22.0.0
Installation
Make sure you have a Plone backend up-and-running at http://localhost:8080/Plone
docker compose up backendStart Volto frontend
If you already have a volto project, just update
package.json:"dependencies": { "@eeacms/volto-matomo": "*" }and
volto.config.js:const addons = ['@eeacms/volto-matomo'];If not, create one with Cookieplone, as recommended by the official Plone documentation for Volto 18+:
uvx cookieplone project cd project-title
Install or update dependencies, then start the project:
make installFor a Cookieplone project, start the backend and frontend in separate terminals:
make backend-start make frontend-startGo to http://localhost:3000
Happy editing!
License
See LICENSE.md for details.