Matomo Client for Angular (ngx-matomo-client)

Common errors

• NG0201: No provider for MatomoService!

  cause 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'

  cause 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'.

  cause 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')

  cause 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.

Warnings

• breaking The 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.
• breaking Angular 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.
• breaking Compatibility 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.
• gotcha Since 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.
• gotcha Incorrect `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.

Install

• npm install ngx-matomo-client npm
• yarn add ngx-matomo-client yarn
• pnpm add ngx-matomo-client pnpm

Imports

• provideMatomo
  wrong:

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

  correct:

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

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

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

  correct:

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

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

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

  correct:

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

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

Quickstart

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())
  ]
});