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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import Client from 'bittorrent-tracker'
✗ const Client = require('bittorrent-tracker').Client
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.
Server
✓ import { Server } from 'bittorrent-tracker'
✗ const Server = require('bittorrent-tracker/server')
The Server class is a named export from the main package entry point, allowing for direct destructuring in ESM.
WebSocketTracker
✓ import { WebSocketTracker } from 'bittorrent-tracker'
✗ import WebSocketTracker from 'bittorrent-tracker/websocket'
Exported as a named export since v11.2.2, providing direct access to the WebSocket tracker implementation.
This quickstart demonstrates how to set up a BitTorrent tracker server and a client that announces to it, handling basic error and update events.
import { Server, Client } from 'bittorrent-tracker'
import { randomBytes } from 'crypto'
// 1. Create a simple tracker server
const server = new Server({
udp: true, // enable udp tracker
http: true, // enable http tracker
ws: true, // enable websocket tracker
stats: true // enable /stats and /stats.json routes
})
server.on('error', err => { console.error('Server error:', err.message) })
server.on('warning', err => { console.warn('Server warning:', err.message) })
server.listen(8000, () => {
console.log('Tracker server listening on port 8000')
// 2. Create a client that announces to this tracker
const infoHash = randomBytes(20) // Identifies the torrent
const peerId = randomBytes(20) // Identifies the peer
const client = new Client({
infoHash: infoHash,
peerId: peerId,
announce: [
`http://127.0.0.1:8000/announce`,
`udp://127.0.0.1:8000`,
`ws://127.0.0.1:8000`
],
port: 6881
})
client.on('error', err => { console.error('Client error:', err.message) })
client.on('warning', err => { console.warn('Client warning:', err.message) })
client.on('update', data => {
console.log(`Client updated: interval=${data.interval} peers=${data.peers.length}`)
})
client.on('peer', peer => {
console.log('Client got a peer:', peer.peerId.toString('hex'))
})
// Start announcing
client.start()
// Announce every 5 seconds with dummy data
const announceInterval = setInterval(() => {
client.update({ uploaded: 10, downloaded: 10, left: 10 })
}, 5000)
// Stop after a while
setTimeout(() => {
console.log('Stopping client and server...')
clearInterval(announceInterval)
client.stop()
server.close()
}, 30000)
})
Errors
Common errors & fixes
TypeError: Client is not a constructor
Attempting to import `Client` using an incorrect method for its export type, common when mixing CommonJS `require` with an ESM default export.
fixFor CommonJS, use `const Client = require('bittorrent-tracker')`. For ESM, use `import Client from 'bittorrent-tracker'`. Error: Unsupported protocol: udp
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.
fixEnsure 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.
ERR_REQUIRE_ESM: Must use import to load ES Module:
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.
fixEither 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.
Audit
Dependencies
undicioptionalOptional dependency for HTTP proxying in Node.js >= 16. Required for custom HTTP agent/dispatcher after v11.0.0.
socksoptionalOptional dependency for SOCKS proxying, used with `Socks.Agent` or `fetch-socks`.