Registry / http-networking / matomo-tracker

matomo-tracker

library2.2.4jsnpmunverified

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.

http-networking data

npm install matomo-tracker

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MATOMO-TRACKER

matomo-tracker

http-networkingjavascriptv2.2.4

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.

MatomoTracker

✓ import MatomoTracker from 'matomo-tracker'

✗ import { MatomoTracker } from 'matomo-tracker'

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

MatomoTracker

✓ const MatomoTracker = require('matomo-tracker')

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

CJS: default export via module.exports.

track

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

✗ track(params)

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.

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

Debug

Known issues

breakingPiwikTracker renamed to MatomoTracker in v2.0.0.

fix

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

affects: <2.0.0

deprecatedv3.0.0-beta drops support for Node <10 and the old callback style.

fix

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

affects: >=3.0.0-beta.0

gotchaThe 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).

affects: >=2.0.0

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

affects: >=2.2.3

breakingv3.0.0-beta is a TypeScript rewrite; type exports may change.

fix

Check the TypeScript definitions and update import types accordingly.

affects: >=3.0.0-beta.0

Errors

Common errors & fixes

TypeError: tracker.track is not a function

Importing the default export as a named import in ESM.

fix

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

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

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: Invalid URL

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

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

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

Upgrade

Version history

2.2.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/matomo-org/matomo-nodejs-tracker ↗

packagehttps://www.npmjs.com/package/matomo-tracker ↗

homepagehttps://matomo.org ↗