{"id":18529,"library":"matomo-tracker","title":"Matomo Node.js Tracker","description":"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.","status":"active","version":"2.2.4","language":"javascript","source_language":"en","source_url":"git://github.com/matomo-org/matomo-nodejs-tracker","tags":["javascript","piwik","matomo","analytics","tracking"],"install":[{"cmd":"npm install matomo-tracker","lang":"bash","label":"npm"},{"cmd":"yarn add matomo-tracker","lang":"bash","label":"yarn"},{"cmd":"pnpm add matomo-tracker","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Default export; named import works in some builds but not guaranteed.","wrong":"import { MatomoTracker } from 'matomo-tracker'","symbol":"MatomoTracker","correct":"import MatomoTracker from 'matomo-tracker'"},{"note":"CJS: default export via module.exports.","wrong":"const { MatomoTracker } = require('matomo-tracker')","symbol":"MatomoTracker","correct":"const MatomoTracker = require('matomo-tracker')"},{"note":"track() is an instance method, not a static or standalone function.","wrong":"track(params)","symbol":"track","correct":"const tracker = new MatomoTracker(siteId, url); tracker.track(params).then(...)"},{"note":"Since v2.2.0, for sending multiple events in one request.","wrong":"","symbol":"trackBulk","correct":"tracker.trackBulk([params1, params2]).then(...)"}],"quickstart":{"code":"import MatomoTracker from 'matomo-tracker';\n\nconst siteId = 1;\nconst matomoUrl = 'https://your-matomo-domain.example.com/matomo.php';\nconst tracker = new MatomoTracker(siteId, matomoUrl);\n\ntracker.track({\n  url: 'http://example.com/page',\n  action_name: 'Page Title',\n  uid: 'user123'\n}).then(response => {\n  console.log('Tracking response:', response);\n}).catch(err => {\n  console.error('Tracking failed:', err);\n});\n\n// Bulk tracking\ntracker.trackBulk([\n  { url: 'http://example.com/page1', action_name: 'Page 1', uid: 'user1' },\n  { url: 'http://example.com/page2', action_name: 'Page 2', uid: 'user2' }\n]).then(responses => {\n  console.log('Bulk tracking responses:', responses);\n}).catch(err => {\n  console.error('Bulk tracking failed:', err);\n});","lang":"typescript","description":"Initializes MatomoTracker with site ID and URL, sends a single page view, then demonstrates bulk tracking of two page views."},"warnings":[{"fix":"Replace all instances of 'PiwikTracker' with 'MatomoTracker' in your code.","message":"PiwikTracker renamed to MatomoTracker in v2.0.0.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Use promises/async-await and upgrade Node to >=10.","message":"v3.0.0-beta drops support for Node <10 and the old callback style.","severity":"deprecated","affected_versions":">=3.0.0-beta.0"},{"fix":"Ensure the URL ends with /matomo.php (or /piwik.php if using Piwik-based forks).","message":"The request URL must point to matomo.php, not the tracking endpoint with /piwik.php or other paths.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Check response data if needed, or rely on HTTP status code via track callback.","message":"HTTP 204 responses are treated as success but contain no body; .then() receives undefined.","severity":"gotcha","affected_versions":">=2.2.3"},{"fix":"Check the TypeScript definitions and update import types accordingly.","message":"v3.0.0-beta is a TypeScript rewrite; type exports may change.","severity":"breaking","affected_versions":">=3.0.0-beta.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use `import MatomoTracker from 'matomo-tracker'` (no curly braces).","cause":"Importing the default export as a named import in ESM.","error":"TypeError: tracker.track is not a function"},{"fix":"Upgrade Node to >=12 or use a bundler that supports package.json exports.","cause":"Using Node.js <12 with a package that defines exports, or misconfigured bundler.","error":"Module not found: Default condition should be last one in the exports field"},{"fix":"Ensure URL includes protocol, e.g., 'https://your-matomo-domain.example.com/matomo.php'.","cause":"Provided tracking URL missing protocol (http/https) or incorrectly formatted.","error":"Error: Invalid URL"},{"fix":"Either provide a callback function or use the returned promise (preferred).","cause":"Using track() with callback style but not providing a callback, and not returning a promise in older versions.","error":"UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'then' of undefined","affected_versions":"<3.0.0-beta"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}