WebTorrent is one npm package with two runtimes and two browser maps

WebRTC in the browser rules out TCP and UDP peers

In node.js the module is an ordinary torrent client, using TCP and UDP to talk to other torrent clients. In the browser it uses WebRTC data channels for peer to peer transport, and the project is blunt about the limit: WebTorrent does not support UDP or TCP peers in the browser. Everything else follows from that.

Making BitTorrent work over WebRTC required protocol changes, and the consequence is a walled garden at the protocol level. A browser based client, called a web peer, can only connect to other clients that support WebTorrent and WebRTC. So a page that hands a visitor a browser instance is not quietly adding that visitor to the existing swarm; they join a parallel one. To seed to those web peers you need a client with WebTorrent support, which is why the project points at WebTorrent Desktop, the webtorrent-hybrid command line program, Instant.io, and Vuze, described as an established client that has already added WebTorrent support.

One package.json carries two different browser field maps

The package is version 3.0.21 and declares `"type": "module"`. What is interesting is that it ships two bundler substitution maps rather than one. The `browser` map is the general one: `crypto`, `fs`, `http`, `net` and `os` all become false, as do `./lib/conn-pool.js`, `./lib/utp.cjs`, `load-ip-set`, `bittorrent-dht` and `ut_pex`. Storage is swapped rather than removed, with `fs-chunk-store` replaced by `fsa-chunk-store`.

The `chromeapp` map is the narrower one. It still drops `os` and `load-ip-set`, but it points `http` and `https` at `@webtorrent/http-node`, points `net` at `chrome-net`, and swaps the storage for `memory-chunk-store` rather than the filesystem backed `fsa-chunk-store`. Same dependency list, two environments, and the differences are all at the edges where node built-ins are unavailable.

Pieces arrive on demand, which is what makes seeking work early

Files are exposed as streams rather than as completed downloads. Pieces are fetched from the network on demand, which is the mechanism behind the claim that seeking is supported even before the torrent is finished. That is a different design from a client that writes a file and seeks within what it has already written, and it is why the client can be attached straight to a video element.

Alongside that, the piece selection strategy switches between sequential and rarest first. Sequential selection suits a stream being watched from the start, rarest first suits completing a file for download, and the client moves between them rather than forcing one policy. The media formats named for a `video` tag include webm, mkv, mp4, ogv and mov, across AV1, H264, HEVC, VP8 and VP9 audio and video codecs plus AAC, FLAC, MP3, OPUS and Vorbis. Browser support is listed as Chrome, Firefox, Opera and Safari.

A magnet URI pulls in four separate discovery mechanisms

The advanced client features are decomposed into small named pieces rather than one monolith. Magnet URI support comes through ut_metadata, which is what fetches the torrent metadata a magnet link does not carry. Peer discovery is split four ways: dht for the distributed hash table, tracker for the conventional announce path, lsd for local service discovery, and ut_pex for exchanging peer lists with peers already connected.

On top of that sits a protocol extension api for adding new extensions, and a list of supported BEPs kept in docs/bep_support.md. The test suite is called comprehensive in the project's own words and is described as running completely offline, which is the reason it can be both fast and dependable, since it needs no peers to be meaningful.

The install for library use is a single command, and it is the same one for node and the browser:

npm install webtorrent

Three install paths lead to three different products

The word WebTorrent covers a library, a command line program and a desktop application, and the install instructions keep them apart. For use in node or the browser as an import, it is `npm install webtorrent`. For the command line program, which lives in its own webtorrent-cli repository, it is a global install. For a desktop application on Mac, Windows or Linux, the project sends you to WebTorrent Desktop instead of giving a command.

npm install webtorrent-cli -g

In the browser there is a third route that avoids any package manager at all: include the `webtorrent.min.js` script on the page from a CDN and start fetching over WebRTC using the BitTorrent protocol. The stated benefit of that route is that it needs no browser plugins, no extensions and no installations, which is a differentiator against anything that asks the visitor to grant an extension permission.

To add it to a build, browserify works without further ceremony, webpack needs extra configuration, and a prebuilt bundle can be imported directly from `webtorrent/dist/webtorrent.min.js` to skip that configuration.

Editorial conclusion

WebTorrent suits a page that needs to stream a file from peers without a plugin, an extension or an install, and node.js code that wants the same client API with a full TCP and UDP peer set. Before you adopt it, check what your peers actually run: a browser instance is a web peer and will only connect to other WebTorrent aware clients, so a site serving web visitors cannot reach the ordinary torrent swarm through them. If you need both worlds to meet, that means shipping a client with WebTorrent support, such as WebTorrent Desktop, and accepting that Vuze is one of the established clients that already carries it.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. webtorrent/webtorrent on GitHub