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.
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.
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
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.
Nguyen Dai Long
AuthorBackend 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.
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.