tus-js-client is a pure JavaScript client for the tus resumable upload protocol, aimed at developers who need file uploads that survive interruptions inside browsers, Node.js, React Native, or Apache Cordova applications.

What it is

The tus protocol is a protocol based on HTTP for resumable file uploads, where resumable means an upload can be interrupted at any moment and resumed without re-uploading the previous data again. tus-js-client is a pure JavaScript client for that protocol, implementing protocol version 1.0.0, and it can be used inside browsers, Node.js, React Native, and Apache Cordova applications. The current line is v4; the project notes that breaking changes were introduced after the previous major release, and the earlier line remains available at the v3.1.3 tag. The project is MIT licensed, lives on GitHub with 2,624 stars and 341 forks, and its homepage is tus.io.

The concrete problem it solves is the standard upload failure mode, where an interrupted transfer must be restarted from zero. An interruption may happen willingly, if the user wants to pause, or by accident in case of a network issue or server outage. tus-js-client replaces the plain whole-file re-upload path with a tus.Upload object that takes a file or input selection, an endpoint, a retryDelays array, and a metadata object carrying values such as filename and filetype. Callbacks including onError, onProgress, and onSuccess expose the transfer lifecycle, with onProgress receiving bytesUploaded and bytesTotal. Because the client can inspect prior state, findPreviousUploads() returns earlier uploads and resumeFromPreviousUpload() continues from one of them, so an unfinished transfer can be picked up rather than discarded.

Key capabilities

• Resumable uploads over the tus protocol version 1.0.0, so an interrupted transfer resumes without re-uploading the previous data.
• One client surface across four runtimes: browsers, Node.js, React Native, and Apache Cordova, per the README and the browser, nodejs, reactnative, cordova, and web topics.
• Configurable retry behaviour through the retryDelays option, shown in the example as [0, 3000, 5000, 10000, 20000].
• Recovery of unfinished transfers with upload.findPreviousUploads() followed by upload.resumeFromPreviousUpload(previousUploads[0]).
• Progress and outcome hooks through onProgress(bytesUploaded, bytesTotal), onError(error), and onSuccess(), the last exposing the resulting upload.url.
• Per-upload metadata attachment, with filename and filetype supplied from the selected file object in the documented example.
• Documentation split across dedicated files: /docs/installation.md, /docs/usage.md, /docs/api.md, /docs/contributing.md, and /docs/faq.md.

Who uses it and how

• Browser applications that wire a file input's change event to a tus.Upload instance and track state through onProgress.
• Node.js processes and services, which appear both in the README's runtime list and in the nodejs topic.
• Mobile and hybrid apps built with React Native or Apache Cordova, where network conditions change mid-transfer.
• Teams that need user-initiated pause and resume, since the README treats a deliberate pause as one of the two interruption cases.
• Projects already running a tus-compatible server, since uploads target an endpoint such as the http://localhost:1080/files/ used in the example.

Getting started

Installation and requirements are documented in /docs/installation.md, with usage and API details in /docs/usage.md and /docs/api.md. The README example constructs a tus.Upload with an endpoint, retryDelays, and metadata, checks findPreviousUploads() before calling start().

How it compares

No comparable client or competing product is named in the provided facts, so this project stands alone in this registry on the evidence available. The only comparative axis the facts support is versioning: v4 is the current line, and users of the prior major release must consult the v3.1.3 tag because breaking changes landed after it.

When to use it — and when not to

This is a client only, so a self-hoster still needs a tus protocol server behind the endpoint; nothing in the facts covers database, object storage, or mail configuration, and no hosted option is described. Projects pinned to the v3 API should stay on the v3.1.3 tag or plan a migration, because v4 carries breaking changes. The README is short and defers nearly everything to files under /docs/, and 77 open issues are tracked, so teams wanting a self-contained single-page reference should expect to read the linked documentation.

input.addEventListener('change', function (e) {
  // Get the selected file from the input element
  var file = e.target.files[0]

  // Create a new tus upload
  var upload = new tus.Upload(file, {
    endpoint: 'http://localhost:1080/files/',
    retryDelays: [0, 3000, 5000, 10000, 20000],
    metadata: {
      filename: file.name,
      filetype: file.type,
    },
    onError: function (error) {
      console.log('Failed because: ' + error)
    },
    onProgress: function (bytesUploaded, bytesTotal) {
      var percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2)
      console.log(bytesUploaded, bytesTotal, percentage + '%')
    },
    onSuccess: function () {
      console.log('Download %s from %s', upload.file.name, upload.url)
    },
  })

  // Check if there are any previous uploads to continue.
  upload.findPreviousUploads().then(function (previousUploads) {
    // Found previous uploads so we select the first one.
    if (previousUploads.length) {
      upload.resumeFromPreviousUpload(previousUploads[0])
    }

    // Start the upload
    upload.start()
  })
})