{"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,"search_vec":"'10':24 '2.2.4':16 'altern':69 'analyt':86 'api':14,44 'better':64 'bulk':50 'compar':67 'custom':38 'customiz':53 'differenti':46 'dimens':39 'enabl':27 'event':35 'former':10 'goal':36 'http':13,43 'introduc':59 'javascript':83 'key':45 'latest':19 'librari':78 'like':70 'matomo':1,9,41,81,85 'nativ':47 'node.js':2,5,23 'offici':77 'option':55 'organ':82 'packag':26 'page':33 'piwik':11,72,84 'piwik-track':71 'promis':48 'releas':21 'request':54 'rewrit':62 'safeti':66 'server':29 'server-sid':28 'side':30 'stabl':20 'support':22,49 'track':12,31,51,87 'tracker':3,73 'type':65 'typescript':61 'upcom':57 'v3.0.0-beta':58 'version':15 'via':40 'view':34 'wrapper':6","created_at":"2026-04-25T07:38:47.346311+00:00","updated_at":"2026-04-25T07:38:47.346311+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://matomo.org","github":"https://github.com/matomo-org/matomo-nodejs-tracker","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/matomo-tracker","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-24","install_tag":null}}