Matomo Node.js Tracker

2.2.4 verified Sat Apr 25 auth: no javascript

A Node.js wrapper for the Matomo (formerly Piwik) tracking HTTP API. Version 2.2.4 is the latest stable release, supporting Node.js >= 10. The package enables server-side tracking of page views, events, goals, and custom dimensions via Matomo's HTTP API. Key differentiators: native promise support, bulk tracking, and customizable request options. The upcoming v3.0.0-beta introduces a TypeScript rewrite with better type safety. Compared to alternatives like 'piwik-tracker', this is the official library from the Matomo organization.

Common errors

error TypeError: tracker.track is not a function ↓

cause Importing the default export as a named import in ESM.

fix

Use import MatomoTracker from 'matomo-tracker' (no curly braces).

error Module not found: Default condition should be last one in the exports field ↓

cause Using Node.js <12 with a package that defines exports, or misconfigured bundler.

fix

Upgrade Node to >=12 or use a bundler that supports package.json exports.

error Error: Invalid URL ↓

cause Provided tracking URL missing protocol (http/https) or incorrectly formatted.

fix

Ensure URL includes protocol, e.g., 'https://your-matomo-domain.example.com/matomo.php'.

error UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'then' of undefined ↓

cause Using track() with callback style but not providing a callback, and not returning a promise in older versions.

fix

Either provide a callback function or use the returned promise (preferred).

Warnings

breaking PiwikTracker renamed to MatomoTracker in v2.0.0. ↓

fix Replace all instances of 'PiwikTracker' with 'MatomoTracker' in your code.

deprecated v3.0.0-beta drops support for Node <10 and the old callback style. ↓

fix Use promises/async-await and upgrade Node to >=10.

gotcha The request URL must point to matomo.php, not the tracking endpoint with /piwik.php or other paths. ↓

fix Ensure the URL ends with /matomo.php (or /piwik.php if using Piwik-based forks).

gotcha HTTP 204 responses are treated as success but contain no body; .then() receives undefined. ↓

fix Check response data if needed, or rely on HTTP status code via track callback.

breaking v3.0.0-beta is a TypeScript rewrite; type exports may change. ↓

fix Check the TypeScript definitions and update import types accordingly.

Install

npm install matomo-tracker

yarn add matomo-tracker

pnpm add matomo-tracker

Imports

MatomoTracker

wrong

import { MatomoTracker } from 'matomo-tracker'

correct

import MatomoTracker from 'matomo-tracker'

Default export; named import works in some builds but not guaranteed.

MatomoTracker

wrong

const { MatomoTracker } = require('matomo-tracker')

correct

const MatomoTracker = require('matomo-tracker')

CJS: default export via module.exports.

track

wrong

track(params)

correct

const tracker = new MatomoTracker(siteId, url); tracker.track(params).then(...)

track() is an instance method, not a static or standalone function.

trackBulk
```
tracker.trackBulk([params1, params2]).then(...)
```
Since v2.2.0, for sending multiple events in one request.

Quickstart

Initializes MatomoTracker with site ID and URL, sends a single page view, then demonstrates bulk tracking of two page views.

import MatomoTracker from 'matomo-tracker';

const siteId = 1;
const matomoUrl = 'https://your-matomo-domain.example.com/matomo.php';
const tracker = new MatomoTracker(siteId, matomoUrl);

tracker.track({
  url: 'http://example.com/page',
  action_name: 'Page Title',
  uid: 'user123'
}).then(response => {
  console.log('Tracking response:', response);
}).catch(err => {
  console.error('Tracking failed:', err);
});

// Bulk tracking
tracker.trackBulk([
  { url: 'http://example.com/page1', action_name: 'Page 1', uid: 'user1' },
  { url: 'http://example.com/page2', action_name: 'Page 2', uid: 'user2' }
]).then(responses => {
  console.log('Bulk tracking responses:', responses);
}).catch(err => {
  console.error('Bulk tracking failed:', err);
});