Repository navigation
matomo-tracker-for-react 2.2.0
✨ What's new
Disable automatic link tracking — linkTracking prop
The headline fix: SPA users whose client-side routing is broken by Matomo's
automatic link-click tracking can now disable it:
<MatomoProvider urlBase="..." siteId={1} path={location.pathname} linkTracking={false} /> Manual trackLink() calls from useMatomo() keep working when it's off.
(Technically, matomo.js only installs link tracking when the
enableLinkTracking instruction is queued, so disabling pushes nothing —
older matomo.js versions have no disableLinkTracking method.)
Strict Mode-safe provider lifecycle
- Tracker initialization moved into an effect — no more script injection or
_paq mutation during React's render phase (React 18 Strict Mode safe). - New destroy() cleanup: the injected matomo.js script is removed and the
MutationObserver disconnected when the provider unmounts or disabled is
toggled on. - trackCookies changes are now applied at runtime (disableCookies).
New hook methods
- trackSiteSearch(keyword, category?, count?, customDimensions?)
- resetUserId() — clear the user ID (e.g. on logout)
- optUserOut() / forgetUserOptOut() — GDPR opt-out/opt-in
Testing & docs
- New end-to-end suite (npm run test:e2e) that drives the example app in
headless Chrome and asserts tracking results against a live Matomo instance
via the Reporting API. - Migration guide for @datapunt/matomo-tracker-react users (MIGRATION.md).
⚠ Notes
- Type narrowing: CustomDimensionsInput no longer includes boolean —
passing customDimensions={false} won't type-check anymore (runtime still
tolerates it). No runtime behavior change. - Dev-only artifact: under <React.StrictMode> in development builds,
page views are tracked twice (Strict Mode mounts effects twice). Production
builds track exactly once. See the README troubleshooting section.
✅ Verified
- 29/29 unit tests, 2/2 live e2e tests
- Production build verified: exactly one page view per load