bTorrent: a WebTorrent client that runs entirely in the browser

A single page client with no backend

bTorrent is a fully-featured WebTorrent browser client written in HTML, JS and CSS, and the homepage is btorrent.xyz.

The repository layout shows how little there is. The top level holds index.html, app.js, style.css, a favicon.ico, a 404.html, a CNAME for the custom domain, a renovate.json, the LICENSE, the README and a views/ directory. There is no server component, no package.json, no build configuration and no test suite. The primary language is recorded as HTML, which is accurate for a project this shape.

That is a deliberate design rather than an unfinished one. The WebTorrent stack runs in the browser, so a client built on it needs no backend, and the deployment story is to serve static files from a CDN with a CDN in front. The README says the website is powered by jsDelivr and CloudFlare, and that nginx is used on the author's server.

The feature list is what makes it interesting rather than a toy. There is an informative GUI with sharing options, downloading from an info hash or a magnet URI, seeding of single or multiple files, per torrent download and upload speed alongside the client totals across all torrents, removing torrents from the client, pause and resume, and client debugging.

Three items are marked as not done. Downloading from a .torrent file is listed as coming soon, as is seeding CORS-enabled remote files and selecting and deselecting files. Use custom trackers and rtcConfig is the one entry left entirely unchecked, and that one matters for the tracker configuration to be present at all.

The nginx rule that decides whether the client loads at all

There is one configuration requirement in the README, and it is stated as a hard rule: you must serve index.html as the default.

For nginx, the conf to use is:

    location / {
        try_files $uri$args $uri$args/ /index.html;
    }

The reason is the shape of the application. A single page application has one entry document and the rest of the paths are client side routes, so a request for a route that does not exist on disk has to fall back to index.html and be resolved by the JavaScript router. Without the try_files fallback, any deep link or refresh on a client route returns the 404 page, which explains the 404.html in the repository root.

The args handling is the other half of the rule. $uri$args appends the query string to the candidate path, so a request for a route with parameters is tried with its query intact before the fallback, and the second candidate $uri$args/ covers the directory form of the same thing.

That is a small amount of configuration, but it is the difference between a client that works when you move around inside it and one that breaks on refresh, and it is the kind of detail that is easy to miss when you deploy a single page app behind a plain static file server.

Turning on debug logging from the browser console

Client debugging is a listed feature, and the mechanism for it is unusually clean.

To enable both the bTorrent debug logging and the WebTorrent logs logging, you run this in the developer console:

localStorage.debug = '*'

And to disable it again:

localStorage.removeItem('debug')

Using localStorage rather than a URL parameter or a build flag means the setting survives a reload and is scoped to the origin, so you can leave debug logging on in a profile you use for development and leave it off everywhere else. The wildcard value is the standard convention for enabling all debug channels at once, and the WebTorrent side reads the same key, which is why one assignment turns on both.

The alternative, a URL parameter, would have been easier to share with a colleague but would also have followed the user around in links and in the browser history, and a build-time flag would have required a separate artefact for a mode you only want occasionally.

The rest of the debugging surface is the per torrent speed display and the client totals, which together give you the two numbers you need to tell a stalled transfer from a slow one, and the client debugging entry in the feature list.

What the top level files tell you about the shape of the client

The file list at the top of the repository is short enough to describe the architecture in a sentence, and a few details in it are worth pulling out.

There is an app.js and a style.css at the root rather than a src/ directory with a bundler config. There is no package.json, so there is no dependency manifest in the repository, which means the libraries the README names are loaded by reference from a CDN at runtime rather than installed and bundled. That is consistent with the static hosting story: the site is jsDelivr and CloudFlare in front of nginx serving files from disk, and the WebTorrent library itself is a browser-native bundle.

The views/ directory is the interesting one given the absence of a build step. The README's link references mention Jade, CoffeeScript, Sass and Harp, which together are a template plus a compile-to-JavaScript language plus a stylesheet preprocessor plus a static server. That combination is what a project would have used to produce a views/ directory of templates and a compiled stylesheet from source. The current tree has a single style.css at the root and a views/ folder, so either the compiled output is committed, or the templates are pre-rendered and the toolchain is only needed by the author.

The CNAME file is the custom domain configuration for GitHub Pages style hosting, and 404.html sits alongside index.html, which is the fallback page the single page application design implies.

The two remaining files are ordinary housekeeping. renovate.json is the dependency update bot configuration, and the LICENSE file carries the MIT terms with copyright Diego Rodríguez Baquero. The favicon.ico and the logo work are credited in the README to jasalo, and the cleanup, ng-file-upload work and other ideas to whitef0x0, which is the usual shape of a small project with a couple of consistent contributors.

None of this adds features. It does tell you what to expect when you open the repository: a small static application you read in the browser, not a codebase you set up and run locally.

A stack that mixes frameworks and hand written files

The Built with list in the README names WebTorrent, AngularJS, Skeleton, Normalize.css, Moment.js, ui-grid, pretty-bytes, ng-file-upload and ng-notify.

That list has an interesting tension with the repository layout. The feature list describes a client written in HTML, JS and CSS, and the primary language is HTML, but the named stack is a mixture of an older framework generation and some small utilities. AngularJS is the application framework, ui-grid provides the torrent grid with per torrent controls, ng-file-upload handles the file selection that the file selection feature still has to finish, and ng-notify is the notification layer behind the share and error messages.

Underneath that, the list also includes a presentation layer from a different era: Skeleton for the base styles, Normalize.css for consistency across browsers, Moment.js for dates, and pretty-bytes for turning byte counts into the readable transfer rates the GUI shows.

The link reference list at the bottom of the README adds four names that the visible Built with list does not mention, Jade, CoffeeScript, Sass and Harp. Those are a templating language, a compile-to-JavaScript language, a stylesheet preprocessor and a static site server, and their presence in the reference definitions suggests an earlier or alternative build path for the views and the stylesheet. The current repository has no package.json and no build script, so if you are picking this up to work on it, the question of how the views/ directory is meant to be rendered is the first thing to establish.

The maintenance signals are modest. renovate.json is present, so dependency updates are automated, the project is MIT licensed with copyright Diego Rodríguez Baquero, and the README thanks jasalo for the logo and favicon and whitef0x0 for cleanup, for ng-file-upload and other ideas.

Editorial conclusion

bTorrent suits a developer who wants to see a complete WebTorrent client in a single page of static files, since the whole thing is an index.html, a stylesheet, a script and a views directory, with no build step and no backend to run. It does not suit you if you need the features still marked as coming soon, namely .torrent file download, CORS-enabled remote file seeding and per file selection, and the unchecked custom trackers and rtcConfig line says the tracker configuration is not in place either. Before you deploy it, serve index.html as the default document with the try_files rule, because the client is a single page application and every other path will otherwise 404, and note that the last push was on 2026-07-02 with no GitHub releases.

Frequently asked questions

Official sources

1. DiegoRBaquero/BTorrent on GitHub
2. Issues
3. License: MIT
4. Project website
5. README