FileDummy Logo
FileDummy
File Upload & Handling

Resumable File Uploads with tus Protocol — JavaScript Guide

Implement resumable file uploads in JavaScript using the tus protocol and tus-js-client. Handles network failures gracefully. Test with a free 1GB dummy file.

September 23, 202610 min read1,420 views
javascripttus-protocolresumable-uploadfile-upload

Network interruptions on mobile networks and unreliable Wi-Fi frequently abort standard HTTP uploads. The tus protocol is an open, standardized specification (tus.io) designed specifically for resumable file uploads over HTTP/1.1 and HTTP/2.

How the tus Protocol Works

Instead of one monolithic request, tus utilizes standard HTTP verbs to coordinate byte offsets:

  • POST: Creates an upload resource URL on the server with metadata and total size.
  • PATCH: Sends byte ranges starting at a specific Upload-Offset.
  • HEAD: Queries the current offset after an unexpected connection drop.
Verified Test Asset.pdf

Simulate heavy network dropouts with our 1GB PDF sample file to test tus-js-client resumption.

Download 1GB PDF Sample →

Using tus-js-client in Modern JavaScript

TypeScript
import * as tus from 'tus-js-client';

export function startResumableUpload(file: File, endpoint: string) {
  const upload = new tus.Upload(file, {
    endpoint: endpoint, // e.g. https://upload.example.com/files/
    retryDelays: [0, 1000, 3000, 5000],
    chunkSize: 5 * 1024 * 1024, // 5MB chunks
    metadata: {
      filename: file.name,
      filetype: file.type,
    },
    onError: (error) => {
      console.error('Upload failed:', error);
    },
    onProgress: (bytesUploaded, bytesTotal) => {
      const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
      console.log(`Uploaded ${bytesUploaded} of ${bytesTotal} bytes (${percentage}%)`);
    },
    onSuccess: () => {
      console.log('Upload finished! URL:', upload.url);
    },
  });

  // Check if a previous upload can be resumed
  upload.findPreviousUploads().then((previousUploads) => {
    if (previousUploads.length > 0) {
      upload.resumeFromPreviousUpload(previousUploads[0]);
    }
    upload.start();
  });

  return upload;
}

Backend Support for tus

  • tusd (Go): The official reference implementation, highly optimized with S3, Google Cloud Storage, and Azure Blob backends.
  • Uppy Companion: Works seamlessly with Uppy.js frontend components.
  • Cloudflare Stream: Uses the tus protocol natively for direct creator video uploads.
NDL

Nguyen Dai Long

Author

Backend Lead • Distributed Systems & Cloud Edge Architecture Specialist

4+ years designing high-throughput file ingestion pipelines, database architectures, and distributed edge storage on Cloudflare R2 & AWS S3. Founder of FileDummy and the NDL Ecosystem.

Was this article helpful?

Click Like to support the author and help other developers discover this guide.

Engineering Discussion & Feedback (0)

Share benchmark results, report edge cases, or ask technical questions.

0/3000

No comments yet. Be the first developer to start the discussion!

Frequently Asked Questions

What is the tus protocol?▾

tus is an open protocol for resumable HTTP file uploads. When a connection drops, the client queries the server for the last byte offset and resumes from that point without re-uploading already-sent data.

Does tus work with mobile browsers?▾

Yes. tus-js-client supports browsers, Node.js, and React Native. The library stores the upload URL in localStorage so uploads resume after a page reload or app restart.

What backend servers support tus?▾

tusd (official Go reference server), Uppy/Companion, tus-node-server, and native support in Cloudflare Stream for video uploads. Major platforms including Vimeo and Transloadit use tus in production.

Related Articles