express-fileupload

express-fileupload is a lightweight Express middleware that wraps the battle-tested Busboy multipart parser to expose uploaded files as a simple req.files object in route handlers. Rather than requiring developers to understand Busboy’s stream-based event API directly, it buffers each uploaded file (in memory by default, or optionally to a temp directory) and hands back a plain object per field with .data, .name, .mimetype, .size, an MD5-style checksum, and a .mv() method for moving the file to its final destination.

The middleware supports common upload concerns out of the box: file-size limits with configurable abort-or-truncate behavior, safe filename sanitization, nested field parsing, temp-file mode for large uploads to avoid memory pressure, and pluggable debug logging. With nearly 500K weekly npm downloads, it remains one of the most widely used file-upload middlewares in the Express ecosystem, though the project is currently seeking additional maintainers and has seen reduced commit activity over the past year.

What You Get

• Uploaded files exposed as req.files.<fieldname> with .data (buffer), .name, .mimetype, .size, and an MD5 (or configurable hash algorithm) checksum
• A .mv() method on each file object for moving it to a destination path, callback- or promise-based
• A useTempFiles mode that streams uploads to a temp directory instead of buffering them in memory, avoiding memory overflow on large or concurrent uploads
• Configurable file-size limits (abortOnLimit, responseOnLimit, limitHandler) built directly on top of Busboy’s limits options
• Filename safety options (safeFileNames, preserveExtension, uriDecodeFileNames) and a parseNested mode for structured form field parsing

Common Use Cases

• Accepting user-uploaded avatars, documents, or attachments in an Express API without hand-rolling multipart parsing
• Handling large file uploads via temp-file storage to avoid holding entire files in server memory
• Building simple internal admin tools or forms that need quick, low-ceremony file upload support
• Migrating from older Connect/Express middleware patterns that expected a straightforward req.files interface

Under The Hood

Architecture: The middleware is organized as a small set of single-purpose modules under lib/: index.js (42 lines) wires up the Express middleware function, processMultipart.js (185 lines) drives the Busboy parsing loop and dispatches fields/files to either memHandler.js or tempFileHandler.js depending on the useTempFiles option, fileFactory.js builds the final file object exposed to req.files, and processNested.js handles the optional nested-field parsing mode. isEligibleRequest.js gates whether a request should be processed at all (checking content-type and method).

Tech Stack: A minimal dependency footprint — Busboy (^1.6.0) is the only runtime dependency, with everything else (nyc, mocha, eslint, supertest) confined to devDependencies. Requires Node.js >= 12.0.0. Testing uses Mocha with supertest for integration-style request tests and nyc for coverage reporting (HTML + text + Coveralls).

Code Quality: The test/ directory contains 13 test files covering core upload paths, size limits, temp files, and nested parsing, run via pretest/posttest hooks that set up and tear down test fixtures. The README itself flags the project as needing additional maintainers for triage, feature work, and dependency/security maintenance, and GitHub activity data shows a drop to zero commits per month over the trailing period — worth factoring in for teams evaluating long-term dependency risk despite the library’s continued wide usage.

API Design: The core value proposition is ergonomic simplicity: enabling the middleware and reading req.files.foo.data requires no configuration for the common case, with Busboy’s more advanced options (like limits) passed straight through rather than re-invented. This keeps the day-one learning curve low, though the file object’s mixed history around the md5 field’s meaning (documented explicitly across three separate version ranges) is a reminder that its API has had some rough edges around backwards compatibility.