Registry / web-framework / express-fileupload

express-fileupload

JSON →
library1.5.2jsnpmunverified

express-fileupload is a straightforward middleware for the Express.js framework, designed to simplify handling multipart/form-data for file uploads. It acts as a wrapper around the `Busboy` parser, exposing uploaded files via `req.files` for easy access. The current stable version is 1.5.2, with minor releases and bug fixes occurring relatively frequently to address issues and introduce small features like custom loggers or hash algorithm options. Key differentiators include its simple API that provides a `mv()` function for relocating uploaded files, direct access to file properties (name, mimetype, size, data buffer), and an option to utilize temporary files on disk instead of memory, which is beneficial for handling large uploads efficiently. The middleware is actively maintained and offers robust handling of file streams.

npm install express-fileupload
INSTALL
IMPORT
SIG · EXPRESS-FILEUPLOAD
E
express-fileupload
web-frameworkjavascriptv1.5.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

fileUpload
import fileUpload from 'express-fileupload';
const fileUpload = require('express-fileupload');
While CommonJS `require` still works, modern Express applications often use ESM `import`. Ensure your project is configured for ESM if using `import`.
fileUpload.options
app.use(fileUpload({ useTempFiles: true, tempFileDir: '/tmp/' }));
app.use(fileUpload.useTempFiles = true);
Configuration options are passed as an object to the `fileUpload` middleware function. Directly assigning properties to the imported module is incorrect.
UploadedFile
// In a TypeScript project: import { UploadedFile } from 'express-fileupload';
import { FileUpload } from 'express-fileupload';
The type for an individual uploaded file is `UploadedFile`. This is primarily used for type-checking in TypeScript projects to correctly define `req.files`.

This quickstart demonstrates a basic Express server configured with `express-fileupload` to handle file uploads. It shows how to initialize the middleware with options like temporary file usage and size limits, how to access uploaded files via `req.files`, and how to move them to a permanent location using the `mv()` method. A simple HTML form is also provided for testing the upload functionality.

import express from 'express'; import fileUpload from 'express-fileupload'; import path from 'path'; import { promises as fs } from 'fs'; const app = express(); const PORT = process.env.PORT || 3000; const UPLOAD_DIR = path.join(process.cwd(), 'uploads'); // Create upload directory if it doesn't exist fs.mkdir(UPLOAD_DIR, { recursive: true }).catch(console.error); // Middleware: Enable file uploads with temporary files app.use(fileUpload({ useTempFiles: true, tempFileDir: '/tmp/', // Ensure this directory exists and is writable limits: { fileSize: 50 * 1024 * 1024 } // 50MB limit })); app.post('/upload', async (req, res) => { if (!req.files || Object.keys(req.files).length === 0) { return res.status(400).send('No files were uploaded.'); } // 'foo' is the name of the input field in the form const uploadedFile = req.files.foo; // Check if uploadedFile is an array (multiple files with same name attribute) // For simplicity, assume single file upload with 'foo' name. if (Array.isArray(uploadedFile)) { return res.status(400).send('Multiple files for a single input field not supported in this example.'); } const uploadPath = path.join(UPLOAD_DIR, uploadedFile.name); try { await uploadedFile.mv(uploadPath); res.send(`File uploaded to ${uploadPath}`); } catch (err) { console.error(err); res.status(500).send(err.message); } }); app.get('/', (req, res) => { res.send(` <h1>Upload a File</h1> <form action="/upload" method="post" enctype="multipart/form-data"> <input type="file" name="foo" /> <input type="submit" value="Upload" /> </form> `); }); app.listen(PORT, () => { console.log(`Server listening on port ${PORT}`); console.log(`Uploads will be saved to ${UPLOAD_DIR}`); });
Debug
Known issues
breakingNode.js versions prior to 12 are no longer supported since v1.3.1. Applications running on older Node.js runtimes will encounter errors or unexpected behavior.
fix
Upgrade your Node.js environment to version 12.0.0 or newer to ensure compatibility and receive security updates.
affects: >=1.3.1
breakingThe behavior of the `md5` property on uploaded file objects has changed multiple times across versions. It was a checksum (before v1.0.0), then a function (v1.0.0-1.1.1), then reverted to a checksum (v1.1.1-1.5.1), and from v1.5.1, it's still a checksum but generated with a configurable `hashAlgorithm` while the property name remains `md5` for backward compatibility.
fix
Developers should explicitly verify the expected `md5` behavior for their specific `express-fileupload` version. If you relied on `md5` being a function between v1.0.0 and v1.1.1, you must update your code. For versions 1.5.1+, consider using the `hashAlgorithm` option for specific hashing needs.
affects: >=1.0.0
gotchaOlder versions (pre-1.5.2) could experience possible conflicts for temporary file names, leading to data corruption or incorrect file handling, especially under high concurrency.
fix
Upgrade to `express-fileupload` v1.5.2 or newer to receive the fix for temporary file name conflicts. This ensures unique temporary file identification.
affects: <1.5.2
gotchaPrototype pollution vulnerability was fixed in v1.3.1. This type of vulnerability could allow an attacker to inject arbitrary properties into object prototypes, potentially leading to remote code execution or denial of service.
fix
Immediately upgrade to `express-fileupload` v1.3.1 or later to mitigate the prototype pollution vulnerability. Regularly scan dependencies for known CVEs.
affects: <1.3.1
gotchaHandling of file names with special characters (e.g., non-ASCII) was problematic in versions prior to v1.4.1, potentially causing upload failures or incorrect file paths.
fix
Upgrade to `express-fileupload` v1.4.1 or newer to correctly process file names containing special characters.
affects: <1.4.1
Errors
Common errors & fixes
TypeError: file.destroy is not a function
An issue in older versions where the `file.destroy` method was incorrectly implemented or missing for certain scenarios, preventing proper cleanup of temporary file streams.
fix
Upgrade `express-fileupload` to v1.4.2 or newer. This version specifically addresses the `TypeError: file.destroy is not a function` error.
TypeError - Cannot read properties of undefined (reading 'includes') in lib/isEligibleRequest.js
This error typically occurred in older versions when the middleware attempted to check request headers or methods on an undefined object, often due to malformed requests or specific edge cases.
fix
Update `express-fileupload` to v1.4.3 or a later version. This release includes a fix for the `TypeError` related to `isEligibleRequest.js`.
Unhandled promise rejection warning
In versions prior to v1.2.1, certain asynchronous operations within the middleware, particularly related to limit handlers or file processing, might not have properly caught or handled promise rejections, leading to unhandled promise warnings in Node.js.
fix
Upgrade `express-fileupload` to v1.2.1 or newer. This version includes updates to better handle promise rejections and prevent unhandled promise warnings.
Error: Request aborted
While not a direct error message *from* express-fileupload, users might encounter this in their server logs when a client prematurely disconnects during a large upload, or when file size limits are exceeded and the connection is terminated by the server without proper cleanup or error propagation in older versions.
fix
Ensure `express-fileupload` is updated to at least v1.4.2, which included stricter request checks and improved handling of abortions on limit exceeding (preventing `next()` from being called after abortion). Implement client-side retry logic and server-side logging for aborted requests.
Upgrade
Version history
1.5.2latest on npm
Audit
Dependencies
busboyrequiredCore parsing engine for multipart/form-data requests, express-fileupload is a wrapper around it.
Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources