Tus Resumable Upload Middleware for Node.js

0.1.7 verified Thu Apr 23 auth: no javascript abandoned

This package, `tus` (version 0.1.7), provides a Node.js middleware for Express and Connect applications, implementing the tus resumable upload protocol. Originally designed for older versions of Express and Connect, it allows clients to pause and resume file uploads, making it suitable for large files or unreliable network conditions. The package's last update was nine years ago, making it effectively abandoned and incompatible with modern Node.js ecosystems, recent Express/Connect versions, and current JavaScript module standards (ESM). It lacks active maintenance, security patches, and contemporary features found in actively developed alternatives like `tus-node-server`. Its release cadence was sporadic, reflecting a period of early development for the tus protocol itself.

Common errors

error TypeError: app.use() requires middleware functions but got a undefined ↓

cause This usually happens when `tus.createServer` is not called or returns undefined, often due to an incorrect `require('tus')` statement or a corrupt installation.

fix

Ensure const tus = require('tus'); is correct and tus.createServer is being invoked with valid options, returning a middleware function.

error Error: Cannot find module 'tus' ↓

cause The package `tus` is not installed or not resolvable in the current project.

fix

Run npm install tus in your project directory to install the package.

error DeprecationWarning: res.send(status) is deprecated ↓

cause The provided example or existing code uses an old Express API for `res.send(status)`, which is deprecated in modern Express.js versions.

fix

Update your Express response handling in the complete callback to res.status(200).send('OK') or res.sendStatus(200) for simple status codes.

error Error: EACCES: permission denied, open '/path/to/uploads/temp_file' ↓

cause The Node.js process does not have write permissions to the specified `directory` for file uploads.

fix

Ensure the user running the Node.js application has read and write permissions to the configured upload directory.

Warnings

breaking This package is heavily outdated (last updated 9 years ago) and is incompatible with modern Node.js versions (e.g., Node.js 14+), Express.js (v4+), and Connect.js. It relies on deprecated APIs and patterns, leading to runtime errors or unexpected behavior. ↓

fix Migrate to an actively maintained tus server implementation, such as `tus-node-server`, which supports modern Node.js and Express versions. This will require a complete re-implementation of the server-side upload logic.

breaking The package is CommonJS-only and does not provide ES Module support. Attempting to `import` it will result in an `ERR_REQUIRE_ESM` or similar error in ES Module contexts. ↓

fix If used in an older CommonJS environment, stick to `require()`. For modern projects using ESM, this package is fundamentally incompatible and requires migration to an ESM-compatible alternative.

gotcha The `complete` callback function in the middleware requires manual handling of the HTTP response (`res`). If you implement `complete`, you must explicitly send a response (e.g., `res.send()`, `res.end()`, `res.status().send()`); otherwise, the client connection may hang. ↓

fix Always ensure `res.status(200).send('OK')` or a similar response mechanism is called within the `complete` callback to properly terminate the HTTP transaction.

breaking Security vulnerabilities are highly probable due to the lack of maintenance. The package has not received updates for almost a decade, making it vulnerable to known and unknown exploits related to file uploads, path traversal, or denial of service. ↓

fix Discontinue use of this package immediately in any production or security-sensitive environment. Replace it with a currently maintained and regularly updated tus server implementation.

Install

npm install tus

yarn add tus

pnpm add tus

Imports

createServer
wrong
```
import { createServer } from 'tus';
```
correct
```
const tus = require('tus');
const uploadMiddleware = tus.createServer({ ... });
```
This package is CommonJS-only and does not support ES Modules. Attempting to use `import` will result in a runtime error.
* as tus
wrong
```
import * as tus from 'tus';
```
correct
```
const tus = require('tus');
```
As a CommonJS package, it exports a single object containing the `createServer` function. ES Module `import * as` syntax is not directly compatible.

Quickstart

Demonstrates how to set up the `tus` middleware with Express, configure the upload directory, set a maximum file size, and handle the `complete` callback for finished uploads.

const express = require('express');
const tus = require('tus');
const path = require('path');
const fs = require('fs');

const app = express();
const port = 3000;

// Ensure the upload directory exists
const uploadDir = path.join(__dirname, 'uploads');
if (!fs.existsSync(uploadDir)) {
    fs.mkdirSync(uploadDir);
}

app.use('/files', tus.createServer({
    directory: uploadDir,
    maxFileSize: 1024 * 1024 * 5, // 5 MB limit
    complete: function(req, res, next) {
        console.log('File upload complete with metadata:', req.upload);
        // In modern Express, use res.status().send() or res.sendStatus()
        // For older Connect/Express, res.end() was common for simple responses.
        res.status(200).send('Upload successful');
        // If not calling next(), ensure the response is manually handled.
    }
}));

app.listen(port, () => {
    console.log(`Tus server listening on port ${port}`);
    console.log(`Upload directory: ${uploadDir}`);
});

// Example: Basic route to serve the client-side uploader (not included in this snippet)
app.get('/', (req, res) => {
    res.send('Tus upload server running. Use a tus client to upload to /files.');
});