{"id":15871,"library":"tus-js-client","title":"tus-js-client Resumable Upload Client","description":"tus-js-client is a robust, pure JavaScript client library that implements the tus resumable upload protocol, enabling reliable and resilient file transfers even across network interruptions. The current stable version is 4.3.1, with the project maintaining an active release cycle that includes frequent patch updates for bug fixes (e.g., bundling issues) and minor versions for feature enhancements like expanded IETF draft support. Major version bumps, such as v4.0.0, primarily serve to update minimum Node.js environment requirements rather than introducing breaking API changes. Key differentiators include its comprehensive support for the tus protocol, cross-platform compatibility across browsers, Node.js environments (requiring Node.js >=18), and Web Workers, alongside native TypeScript type definitions for an improved developer experience. It provides a foundational solution for developers needing to handle large file uploads with progress tracking, pause/resume functionality, and error recovery.","status":"active","version":"4.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/tus/tus-js-client","tags":["javascript","tus","resumable","upload","protocol","progress","file","browser","typescript"],"install":[{"cmd":"npm install tus-js-client","lang":"bash","label":"npm"},{"cmd":"yarn add tus-js-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add tus-js-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for initiating and managing tus uploads. CommonJS users should access it via `const { Upload } = require('tus-js-client')` or `const tus = require('tus-js-client'); const Upload = tus.Upload;`.","wrong":"const Upload = require('tus-js-client').Upload","symbol":"Upload","correct":"import { Upload } from 'tus-js-client'"},{"note":"Provides the default configuration options for the Upload class. Useful for extending or modifying base behavior.","wrong":"const defaultOptions = require('tus-js-client').defaultOptions","symbol":"defaultOptions","correct":"import { defaultOptions } from 'tus-js-client'"},{"note":"TypeScript users can import this interface for type-checking upload configuration objects.","symbol":"UploadOptions","correct":"import type { UploadOptions } from 'tus-js-client'"}],"quickstart":{"code":"import { Upload } from 'tus-js-client';\nimport fs from 'fs'; // For Node.js environment\n\n// In a browser, file would be from an <input type=\"file\"> event\n// In Node.js, you might read a file from the filesystem\nconst filePath = './path/to/your/file.txt';\nconst file = fs.createReadStream(filePath); // Or a Blob/File object in browser\n\nconst upload = new Upload(file, {\n  endpoint: 'https://master.tus.io/files/',\n  retryDelays: [0, 1000, 3000, 5000],\n  metadata: {\n    filename: 'my-document.txt',\n    filetype: 'text/plain'\n  },\n  headers: { // Example of custom headers\n    'X-Requested-With': 'XMLHttpRequest'\n  },\n  onProgress: (bytesUploaded, bytesTotal) => {\n    const percentage = (bytesUploaded / bytesTotal * 100).toFixed(2);\n    console.log(`Uploaded ${bytesUploaded} of ${bytesTotal} bytes (${percentage}%)`);\n  },\n  onSuccess: () => {\n    console.log('Upload finished:', upload.url);\n  },\n  onError: (error) => {\n    console.error('Failed to upload:', error);\n    if (error.originalRequest) {\n        console.error('Response status:', error.originalRequest.getStatus());\n        console.error('Response text:', error.originalRequest.getResponseText());\n    }\n  }\n});\n\n// Check if there are any previous uploads to resume\nupload.findPreviousUploads().then(previousUploads => {\n  if (previousUploads.length) {\n    upload.resumeFromPreviousUpload(previousUploads[0]);\n  }\n  upload.start();\n});","lang":"typescript","description":"Demonstrates a basic file upload using the `Upload` class, including progress tracking, success, and error handling, with support for resuming previous uploads. This example is adaptable for both Node.js (using `fs.createReadStream`) and browser environments."},"warnings":[{"fix":"Ensure your Node.js environment is updated to version 18 or higher before upgrading to tus-js-client v4.x.","message":"Version 4.0.0 of tus-js-client dropped support for Node.js v14 and v16. It now requires Node.js v18 or newer.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to tus-js-client v4.3.1 or newer to benefit from fixes addressing these bundling problems (e.g., issues #748, #715). Ensure your bundler configuration is up-to-date and correctly handles Node.js polyfills if targeting browser environments.","message":"Bundling issues with Webpack or Rollup, specifically related to `node:` protocol imports and incorrect handling of Node.js `Buffer` context, have been reported and patched across several minor versions.","severity":"gotcha","affected_versions":">=4.0.0 <4.3.1"},{"fix":"Update to tus-js-client v4.2.1 or newer for the corrected `onSuccess` callback type definition. No code changes are typically required, but type-checking will now be accurate.","message":"The type definition for the `onSuccess` callback was incorrect in earlier versions of v4, potentially leading to TypeScript errors when accessing the `lastResponse` parameter.","severity":"gotcha","affected_versions":">=4.0.0 <4.2.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade to tus-js-client v4.2.2 or newer, which explicitly drops the `node:` protocol for imports to resolve these bundling issues. Ensure your bundler is updated and configured correctly.","cause":"This error typically occurs in bundling environments (like Webpack or Rollup) when `tus-js-client` attempts to import Node.js built-in modules using the `node:` protocol specifier, which some bundlers do not natively support or are incorrectly configured for.","error":"Error: Unhandled Scheme 'node:'"},{"fix":"Update to tus-js-client v4.3.1 or later. This version contains a patch specifically addressing this `Buffer` context issue during bundling (related to issue #748).","cause":"This error surfaced during bundling (e.g., Rollup) due to a specific interaction with how Node.js's `Buffer` type was handled and potentially polyfilled in certain environments, leading to incorrect context (`this`) being passed.","error":"TypeError: The 'this' context of the 'buffer' module is not allowed to be called with a non-Buffer argument"},{"fix":"Upgrade to tus-js-client v4.0.1 or newer. This version removed a dependency on the global `window` object, improving compatibility with Web Workers and other environments without a `window` global.","cause":"Although `tus-js-client` is designed to work in both browser and Node.js environments, older versions could exhibit `window` dependency issues in non-browser contexts like Web Workers or certain server-side rendering setups.","error":"ReferenceError: window is not defined"}],"ecosystem":"npm"}