Skip to main content

​
Migrating to v2.0

WebTorrent v2.0 is a major release with breaking changes. This guide will help you migrate your application.
WebTorrent v2.0 requires Node.js 16 or later. Node.js 12 and 14 are no longer supported.

​
Breaking Changes

​
ESM Only

WebTorrent v2.0 is now ESM only. CommonJS require() is no longer supported. Before (v1.x): 
const WebTorrent = require('webtorrent')
After (v2.0): 
import WebTorrent from 'webtorrent'

​
Deprecated getBuffer() Method

The file.getBuffer() method has been deprecated in favor of standard Web APIs. Before (v1.x): 
file.getBuffer((err, buffer) => {
  if (err) throw err
  console.log(buffer)
})
After (v2.0): 
// Use arrayBuffer() - returns a Promise
const buffer = await file.arrayBuffer()
console.log(buffer)

// Or use the stream API
const stream = file.stream()
for await (const chunk of stream) {
  console.log(chunk)
}

​
W3C-like File API

File objects now follow the W3C File API more closely: 
// New standard methods
await file.arrayBuffer()  // Get as ArrayBuffer
await file.text()          // Get as text string
file.stream()              // Get ReadableStream
await file.blob()          // Get as Blob

​
Storage Changes in Browser

WebTorrent v2.0 uses persistent storage (File System Access API + IndexedDB) in the browser instead of memory-only storage.
This means torrents can persist across browser sessions, but you need more careful cleanup.
Important: Always destroy torrents when done: 
torrent.destroy() // Clean up storage

​
Render Media Deprecation

The file.renderTo() method has been removed. Use file.streamTo() instead. Before (v1.x): 
file.renderTo('video')
After (v2.0): 
const video = document.querySelector('video')
file.streamTo(video)

​
New Features in v2.0

​
Service Worker Support

v2.0 adds first-class Service Worker support for better streaming: 
// Register service worker
const controller = await navigator.serviceWorker.register('./sw.min.js', { 
  scope: './' 
})
await navigator.serviceWorker.ready

// Create server with controller
client.createServer({ controller })

// Stream to video
file.streamTo(document.querySelector('video'))

​
Improved File Streaming

Better performance with the new streaming architecture: 
file.on('stream', ({ stream, file, req }) => {
  console.log(`Streaming ${file.name}`)
  console.log(`Range: ${req.headers.range}`)
})

​
Built-in WebRTC Support

v2.3+ includes built-in WebRTC without needing separate packages.

​
Migrating from v1.9 to v2.0

​
Step-by-Step Migration

1

Update Node.js

Ensure you’re running Node.js 16 or later:
node --version  # Should be v16.0.0 or higher
2

Update package.json

Update your dependencies:
{
  "type": "module",
  "dependencies": {
    "webtorrent": "^2.0.0"
  }
}
3

Convert to ESM

Replace all require() with import:
// Old
const WebTorrent = require('webtorrent')
const fs = require('fs')

// New
import WebTorrent from 'webtorrent'
import fs from 'fs'
4

Update File API Calls

Replace deprecated methods:
// Old
file.getBuffer((err, buf) => {
  // ...
})

// New
const buffer = await file.arrayBuffer()
5

Update Render Calls

Use the new streaming API:
// Old
file.renderTo('video', { autoplay: true })

// New
const video = document.querySelector('video')
file.streamTo(video)
video.autoplay = true
6

Test Your Application

Run your test suite and verify all functionality works.

​
Version 2.x.x Changes

​
v2.8.0 (2025-08)

  • Feature: Updated fs-chunk-store to v5 for better performance
  • Feature: Peers stored as Map instead of Array for performance improvements

​
v2.7.0 (2025-08)

  • Performance: Major performance improvements with peer management
  • Fix: Connection count tracking

​
v2.6.0 (2025-04)

  • Feature: Added option to store the bitfield in the file system
  • Performance: Reduced memory usage for large torrents

​
v2.5.0 (2024-08)

  • Breaking: Dropped IndexedDB chunk store in favor of File System Access API
  • Performance: Significantly reduced memory usage in browser

​
v2.4.0 (2024-06)

  • Feature: Added seedOutgoingConnections option to control outbound connections when seeding
const client = new WebTorrent({
  seedOutgoingConnections: false // Only accept inbound connections when seeding
})

​
v2.3.0 (2024-05)

  • Feature: Built-in WebRTC support (no longer requires separate package)
  • Performance: Faster peer connections

​
v2.2.0 (2024-03)

  • Feature: Refactored file selections with non-overlapping data structure
  • Performance: Improved piece selection algorithm

​
Common Migration Issues

Add "type": "module" to your package.json:
{
  "type": "module",
  "name": "my-app"
}
Or rename files from .js to .mjs.
Replace with the new async methods:
// Instead of getBuffer
const buffer = await file.arrayBuffer()

// Or for Node.js Buffer
const buffer = Buffer.from(await file.arrayBuffer())
Ensure you’re properly registering the service worker:
const controller = await navigator.serviceWorker.register('./sw.min.js', {
  scope: './'
})
await navigator.serviceWorker.ready
client.createServer({ controller })
Make sure sw.min.js is served from your web server.
You’re trying to use CommonJS in an ESM context. Convert to ESM:
// Don't use
const WebTorrent = require('webtorrent')

// Use
import WebTorrent from 'webtorrent'

​
Webpack Configuration

If you’re using Webpack, you may need to update your configuration for v2.0: 
// webpack.config.js
export default {
  resolve: {
    fallback: {
      // WebTorrent v2.0 requires these polyfills for browser
      fs: false,
      net: false,
      tls: false
    }
  },
  module: {
    rules: [
      {
        test: /\.m?js$/,
        type: 'javascript/auto',
        resolve: {
          fullySpecified: false
        }
      }
    ]
  }
}
Or simply use the pre-built version: 
import WebTorrent from 'webtorrent/dist/webtorrent.min.js'

​
Getting Help

If you encounter issues during migration:
For production applications, thoroughly test your migration in a staging environment before deploying.