Registry / observability / ngx-matomo-client

ngx-matomo-client

library9.0.1jsnpmunverified

ngx-matomo-client is a robust, actively maintained library providing seamless integration of Matomo (formerly Piwik) analytics into Angular applications. The current stable version is 9.0.1, offering compatibility with Angular 21. The library generally follows Angular's release cadence, providing updates for new major Angular versions, typically within weeks of their release. Key differentiators include its focus on privacy-respecting analytics, explicit support for Angular's module-less applications (since v8.0.0), and the ability to run tracking operations outside Angular's change detection zone for improved performance and stability. This package consolidates functionality previously split across `@ngx-matomo/tracker` and `@ngx-matomo/router` since version 5, simplifying usage and reducing overhead for developers integrating Matomo with Angular's routing.

observability web-framework

npm install ngx-matomo-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NGX-MATOMO-CLIENT

ngx-matomo-client

observabilityjavascriptv9.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

provideMatomo

✓ import { provideMatomo } from 'ngx-matomo-client';

✗ import { provideMatomo } from '@ngx-matomo/tracker';

This is the modern, standalone function for providing Matomo in root or feature modules, replacing legacy `MatomoModule.forRoot()`.

MatomoService

✓ import { MatomoService } from 'ngx-matomo-client';

✗ import { MatomoService } from '@ngx-matomo/tracker';

The primary service for interacting with the Matomo tracker instance. Inject this into components or services.

MatomoRouterInitializer

✓ import { MatomoRouterInitializer } from 'ngx-matomo-client';

✗ import { NgxMatomoRouterModule } from '@ngx-matomo/router';

Used with `withRouter()` for automatic page view tracking with Angular Router. The legacy module `MatomoRouterModule` was deprecated.

This quickstart sets up Matomo in a standalone Angular application, including router tracking and an example of manually tracking a custom event. Replace `trackerUrl` and `siteId` with your Matomo instance details.

import { Component, OnInit } from '@angular/core'; import { MatomoService, provideMatomo, withRouter } from 'ngx-matomo-client'; import { bootstrapApplication } from '@angular/platform-browser'; import { provideRouter, RouterOutlet } from '@angular/router'; @Component({ selector: 'app-root', standalone: true, imports: [RouterOutlet], template: ` <h1>Welcome to Matomo Tracking!</h1> <p>Check your Matomo dashboard for tracking data.</p> <button (click)="trackCustomEvent()">Track Custom Event</button> ` }) export class AppComponent implements OnInit { constructor(private matomoService: MatomoService) {} ngOnInit(): void { // Manually track a page view if not using router integration // this.matomoService.trackPageView(); } trackCustomEvent(): void { this.matomoService.trackEvent('UserInteraction', 'ButtonClick', 'CustomButton'); console.log('Custom event tracked!'); } } bootstrapApplication(AppComponent, { providers: [ provideRouter([]), provideMatomo({ trackerUrl: 'https://your-matomo-domain.com/matomo.php', siteId: 1 }, withRouter()) ] });

Debug

Known issues

breakingThe package structure changed significantly in v5. The library was consolidated from `@ngx-matomo/tracker` and `@ngx-matomo/router` into a single `ngx-matomo-client` package. Direct imports from the old packages will fail.

fix

Update all `import` statements to use `ngx-matomo-client`. Refer to the migration guide for specific class and function renames/relocations if upgrading from v4 or older.

affects: >=5.0.0

breakingAngular module-based setup (e.g., `MatomoModule.forRoot()`) is largely superseded by standalone `provideMatomo` since v8.0.0, aligning with modern Angular practices. While legacy modules might still work for compatibility, the recommended approach is the standalone API.

fix

Migrate your application's Matomo initialization from `MatomoModule.forRoot()` in `app.module.ts` to `provideMatomo()` in `main.ts` or `app.config.ts`, especially for new standalone components or applications.

affects: >=8.0.0

breakingCompatibility with Angular versions is strict. Each major `ngx-matomo-client` version typically supports a specific major Angular version. For instance, v9.x requires Angular 21, v8.x requires Angular 20, and so on. Mismatched versions will lead to peer dependency errors.

fix

Ensure your `ngx-matomo-client` version matches your Angular project's version according to the compatibility table in the package's README. Upgrade both `ngx-matomo-client` and Angular together.

affects: >=5.0.0

gotchaSince v9.0.0, Matomo tracking runs outside Angular's zone by default. This is generally a performance improvement but might affect debugging or change detection if you rely on tracker side effects to trigger Angular updates without manual intervention.

fix

Most applications will benefit from this. If specific scenarios require tracking within the Angular zone, consider wrapping `MatomoService` calls with `ngZone.run()` if absolutely necessary, or ensure your component logic correctly triggers change detection.

affects: >=9.0.0

gotchaIncorrect `trackerUrl` or `siteId` configuration will result in Matomo tracking calls failing silently or reporting to the wrong Matomo instance. This is a common setup error.

fix

Double-check your `trackerUrl` (including `matomo.php` or `piwik.php`) and `siteId` values against your Matomo server configuration. Use your browser's network tab to verify that `matomo.php` requests are being sent correctly.

affects: All versions

Errors

Common errors & fixes

NG0201: No provider for MatomoService!

The MatomoService has not been properly provided at the application root or the relevant feature module.

fix

Ensure `provideMatomo()` is called in your `main.ts` or `app.config.ts` (for standalone applications) or `MatomoModule.forRoot()` (for legacy module-based applications) is imported in your root module.

Can't resolve '@angular/common' in 'node_modules/ngx-matomo-client'

A mismatch exists between the `ngx-matomo-client` version and your Angular version, leading to an incompatible peer dependency.

fix

Check the `ngx-matomo-client` README's compatibility table and align your `ngx-matomo-client` package version with your Angular version. For example, if on Angular 21, use `ngx-matomo-client@9`.

Property 'trackPageView' does not exist on type 'MatomoService'.

You might be using an older version of the library or have a corrupted `node_modules` installation, or there's a TypeScript type inference issue.

fix

Ensure you are using `ngx-matomo-client` (not legacy `@ngx-matomo/tracker`). Verify your `ngx-matomo-client` version is up-to-date and run `npm install` or `yarn install` to refresh dependencies. Check your `tsconfig.json` for proper type resolution.

ERROR TypeError: Cannot read properties of undefined (reading 'trackPageView')

The Matomo tracker instance (window._paq) might not be initialized when `MatomoService` methods are called, often due to deferred configuration or incorrect initialization timing.

fix

Ensure Matomo is initialized before calling tracking methods. For deferred or manual initialization, use `MatomoInitializerService.initialize()` once the necessary configuration (e.g., from an API) is available. For standard setup, ensure `provideMatomo` is correctly configured.

Upgrade

Version history

9.0.1latest on npm

Audit

Dependencies

@angular/commonrequiredAngular core functionality for common directives and pipes.

@angular/corerequiredCore Angular framework required for any Angular application.

@angular/routeroptionalRequired for automatic page view tracking via Angular's router.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/EmmanuelRoux/ngx-matomo-client ↗

packagehttps://www.npmjs.com/package/ngx-matomo-client ↗

homepagehttps://ngx-matomo-client.org ↗