{"id":12895,"library":"bittorrent-tracker","title":"BitTorrent Tracker Implementation","description":"bittorrent-tracker is a Node.js library offering a comprehensive, robust, and well-tested implementation of both a BitTorrent tracker client and server. It currently stands at version 11.2.2 and sees active, frequent releases (multiple times per year), ensuring ongoing development and bug fixes. Key differentiators include its support for all mainstream tracker types—HTTP, UDP (BEP 15), and WebTorrent (BEP forthcoming)—alongside IPv4 and IPv6 compatibility and the BitTorrent scrape extension. The module provides statistics via a web interface or JSON API and is a core component used by popular clients like WebTorrent, peerflix, and playback, making it a reliable choice for building BitTorrent-enabled applications.","status":"active","version":"11.2.2","language":"javascript","source_language":"en","source_url":"git://github.com/webtorrent/bittorrent-tracker","tags":["javascript","bittorrent","p2p","peer","peer-to-peer","stream","torrent","tracker","wire"],"install":[{"cmd":"npm install bittorrent-tracker","lang":"bash","label":"npm"},{"cmd":"yarn add bittorrent-tracker","lang":"bash","label":"yarn"},{"cmd":"pnpm add bittorrent-tracker","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional dependency for HTTP proxying in Node.js >= 16. Required for custom HTTP agent/dispatcher after v11.0.0.","package":"undici","optional":true},{"reason":"Optional dependency for SOCKS proxying, used with `Socks.Agent` or `fetch-socks`.","package":"socks","optional":true}],"imports":[{"note":"The Client class is the primary export. It's available as a default ESM import and also as a named export. For CommonJS, `const Client = require('bittorrent-tracker')` retrieves the constructor directly.","wrong":"const Client = require('bittorrent-tracker').Client","symbol":"Client","correct":"import Client from 'bittorrent-tracker'"},{"note":"The Server class is a named export from the main package entry point, allowing for direct destructuring in ESM.","wrong":"const Server = require('bittorrent-tracker/server')","symbol":"Server","correct":"import { Server } from 'bittorrent-tracker'"},{"note":"Exported as a named export since v11.2.2, providing direct access to the WebSocket tracker implementation.","wrong":"import WebSocketTracker from 'bittorrent-tracker/websocket'","symbol":"WebSocketTracker","correct":"import { WebSocketTracker } from 'bittorrent-tracker'"}],"quickstart":{"code":"import { Server, Client } from 'bittorrent-tracker'\nimport { randomBytes } from 'crypto'\n\n// 1. Create a simple tracker server\nconst server = new Server({\n  udp: true, // enable udp tracker\n  http: true, // enable http tracker\n  ws: true, // enable websocket tracker\n  stats: true // enable /stats and /stats.json routes\n})\n\nserver.on('error', err => { console.error('Server error:', err.message) })\nserver.on('warning', err => { console.warn('Server warning:', err.message) })\n\nserver.listen(8000, () => {\n  console.log('Tracker server listening on port 8000')\n\n  // 2. Create a client that announces to this tracker\n  const infoHash = randomBytes(20) // Identifies the torrent\n  const peerId = randomBytes(20) // Identifies the peer\n\n  const client = new Client({\n    infoHash: infoHash,\n    peerId: peerId,\n    announce: [\n      `http://127.0.0.1:8000/announce`,\n      `udp://127.0.0.1:8000`,\n      `ws://127.0.0.1:8000`\n    ],\n    port: 6881\n  })\n\n  client.on('error', err => { console.error('Client error:', err.message) })\n  client.on('warning', err => { console.warn('Client warning:', err.message) })\n\n  client.on('update', data => {\n    console.log(`Client updated: interval=${data.interval} peers=${data.peers.length}`)\n  })\n\n  client.on('peer', peer => {\n    console.log('Client got a peer:', peer.peerId.toString('hex'))\n  })\n\n  // Start announcing\n  client.start()\n\n  // Announce every 5 seconds with dummy data\n  const announceInterval = setInterval(() => {\n    client.update({ uploaded: 10, downloaded: 10, left: 10 })\n  }, 5000)\n\n  // Stop after a while\n  setTimeout(() => {\n    console.log('Stopping client and server...')\n    clearInterval(announceInterval)\n    client.stop()\n    server.close()\n  }, 30000)\n})\n","lang":"javascript","description":"This quickstart demonstrates how to set up a BitTorrent tracker server and a client that announces to it, handling basic error and update events."},"warnings":[{"fix":"For proxying HTTP/HTTPS requests, configure `proxyOpts.httpAgent` or `proxyOpts.httpsAgent` by passing an `undici.ProxyAgent` (Node.js >=16) or a standard `http.Agent`/`https.Agent`. Ensure `undici` is installed if used.","message":"Version 11.0.0 removed the `simple-get` dependency and requires users to explicitly pass an `undici` Agent (for Node.js 16+) or `http.Agent` for HTTP proxying.","severity":"breaking","affected_versions":">=11.0.0"},{"fix":"Always use `Buffer.from()` (e.g., `Buffer.from('your-data')`) when creating Buffer instances to ensure compatibility and avoid deprecation warnings.","message":"The `new Buffer()` constructor is deprecated in Node.js. Although it may still work, it can lead to warnings or errors in future Node.js versions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 16.0.0 or newer to meet the package's engine requirements.","message":"The package requires Node.js version 16.0.0 or higher as specified in its `engines` field. Running on older Node.js versions will result in an engine error.","severity":"gotcha","affected_versions":"<16.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const Client = require('bittorrent-tracker')`. For ESM, use `import Client from 'bittorrent-tracker'`.","cause":"Attempting to import `Client` using an incorrect method for its export type, common when mixing CommonJS `require` with an ESM default export.","error":"TypeError: Client is not a constructor"},{"fix":"Ensure the tracker server is initialized with the correct protocol options (e.g., `udp: true`, `http: true`, `ws: true`) in its constructor. Verify the `announce` URLs in the client exactly match the protocols enabled on the server and are correctly formatted.","cause":"The tracker client is attempting to announce to a protocol (e.g., UDP) that is not supported or explicitly enabled on the tracker server, or the tracker URL is malformed.","error":"Error: Unsupported protocol: udp"},{"fix":"Either convert your consuming file or project to an ECMAScript Module (ESM) by setting `\"type\": \"module\"` in your `package.json` or by using the `.mjs` file extension, and then use `import` statements. Alternatively, ensure your build process correctly transpiles ESM to CommonJS if targeting older environments.","cause":"A CommonJS module is attempting to `require` `bittorrent-tracker` or one of its dependencies that has transitioned to be a pure ESM module, leading to a module loading error.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module:"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}