Handling File Uploads in Node.js Web Applications
busboy, express-fileupload, formidable, and multer are all npm packages designed to parse incoming file uploads from HTTP requests in Node.js applications. They handle multipart/form-data payloads commonly used when submitting forms with file inputs. Each provides mechanisms to extract uploaded files and form fields, but they differ significantly in architecture, integration style, and flexibility. These libraries enable server-side processing of user-uploaded content such as images, documents, or other binary data.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Handling File Uploads in Node.js: busboy vs express-fileupload vs formidable vs multer
When your web app needs to accept files from users — whether profile pictures, documents, or media — you’ll quickly run into the complexity of parsing multipart/form-data requests. The four packages compared here (busboy, express-fileupload, formidable, multer) all solve this problem, but with very different philosophies. Let’s break down how they work, where they shine, and what trade-offs you’ll face.
🧱 Architecture: Streaming Parser vs Middleware vs Standalone
busboy is a low-level streaming parser. It doesn’t assume anything about your framework or storage strategy. You listen to stream events and decide what to do with each file chunk.
// busboy: manual stream handling
const http = require('http');
const Busboy = require('busboy');
http.createServer((req, res) => {
if (req.method === 'POST') {
const busboy = new Busboy({ headers: req.headers });
busboy.on('file', (fieldname, file, filename) => {
file.on('data', (data) => {
// Handle chunk manually (e.g., pipe to cloud storage)
});
file.on('end', () => {
console.log('File finished');
});
});
busboy.on('finish', () => res.end('Done'));
req.pipe(busboy);
}
});
express-fileupload is an Express-specific middleware that auto-parses uploads and attaches them to req.files as buffered objects.
// express-fileupload: automatic buffering
const express = require('express');
const fileUpload = require('express-fileupload');
const app = express();
app.use(fileUpload());
app.post('/upload', (req, res) => {
// File is already buffered in memory (or temp file)
console.log(req.files.myFile.data); // Buffer
res.send('Uploaded');
});
formidable is a standalone parser that works outside any framework but integrates easily. It supports promises and callbacks, and gives you control over where files land.
// formidable: promise-based parsing
const express = require('express');
const { formidable } = require('formidable');
const app = express();
app.post('/upload', async (req, res) => {
const { fields, files } = await formidable().parse(req);
// files.myFile is an object with filepath, mimetype, etc.
res.json({ uploaded: files.myFile[0].filepath });
});
multer is an Express middleware that uses storage engines to decide whether to keep files in memory or write them to disk.
// multer: middleware with storage config
const express = require('express');
const multer = require('multer');
const app = express();
const upload = multer({ dest: 'uploads/' });
app.post('/upload', upload.single('myFile'), (req, res) => {
// File saved to 'uploads/' with random name
console.log(req.file.path); // e.g., 'uploads/abc123'
res.send('Saved');
});
💾 Storage Strategy: Memory, Disk, or Custom?
How each library handles file storage is a major differentiator.
-
busboy: Does nothing by default. You must implement your own logic — pipe to disk, buffer in memory, or stream directly to S3. Maximum flexibility, maximum responsibility. -
express-fileupload: Buffers small files (<50MB by default) in memory; larger files go to temporary disk files. You can adjust thresholds, but you can’t easily customize the destination path without extra code. -
formidable: Writes all files to temporary disk locations by default, but you can switch to memory-only mode or specify a custom upload directory. -
multer: Offers two built-in storage engines:MemoryStorage(holds file as a Buffer) andDiskStorage(writes to a configurable directory with optional filename control). You can also build custom storage engines.
💡 If you’re uploading directly to cloud storage (like AWS S3),
busboyis often the best starting point because it avoids unnecessary disk I/O. The others may force you to write to disk first, then read and upload — wasting time and space.
⚙️ Configuration and Control
busboy gives you granular control over parsing options like field size limits, file size limits, and character encoding — but you configure it at instantiation.
const busboy = new Busboy({
headers: req.headers,
limits: { fileSize: 10 * 1024 * 1024 } // 10MB
});
express-fileupload lets you set global limits via middleware options:
app.use(fileUpload({
limits: { fileSize: 5 * 1024 * 1024 },
useTempFiles: true,
tempFileDir: '/tmp/'
}));
formidable supports per-request configuration:
const form = formidable({
maxFileSize: 10 * 1024 * 1024,
uploadDir: './uploads',
keepExtensions: true
});
multer allows per-route or global configuration, including file filtering:
const upload = multer({
dest: 'uploads/',
limits: { fileSize: 5 * 1024 * 1024 },
fileFilter: (req, file, cb) => {
if (file.mimetype.startsWith('image/')) cb(null, true);
else cb(new Error('Only images allowed'));
}
});
🔄 Framework Integration
busboy: Framework-agnostic. Works with Express, Koa, Fastify, or raw Node.js HTTP servers.express-fileupload: Only works with Express. Tightly coupled toreqandresobjects.formidable: Framework-agnostic. Pass it a request object, and it works anywhere.multer: Express-only. Designed as Express middleware and relies on its pattern.
If you’re not using Express, your choices narrow to busboy or formidable.
🛑 Error Handling
All four libraries throw or emit errors when limits are exceeded or malformed requests arrive, but their styles differ:
busboy: Emits an'error'event on the parser instance.express-fileupload: Passes errors to Express’s error-handling middleware (vianext(err)).formidable: Rejects the promise (in async mode) or calls the callback with an error.multer: Passes errors to Express’s error-handling middleware.
This means busboy and formidable require explicit error catching in non-Express contexts, while the Express-focused tools integrate cleanly into Express’s error pipeline.
📦 Real-World Recommendations
Scenario 1: Simple Express App with Profile Picture Uploads
You just need to save user avatars to disk with basic size checks.
- ✅ Best choice:
multer - Why? Built-in disk storage, easy validation, and clean Express integration.
const upload = multer({
dest: 'public/avatars/',
limits: { fileSize: 2 * 1024 * 1024 }
});
app.post('/avatar', upload.single('avatar'), (req, res) => {
// Done
});
Scenario 2: Streaming Large Video Files Directly to S3
You don’t want files touching your server’s disk.
- ✅ Best choice:
busboy - Why? Lets you pipe file streams straight to S3 without intermediate storage.
busboy.on('file', (fieldname, file) => {
const uploadParams = { Bucket: 'my-bucket', Key: 'video.mp4', Body: file };
s3.upload(uploadParams).promise();
});
Scenario 3: Non-Express Server (e.g., Fastify or Raw HTTP)
You’re avoiding Express for performance or architectural reasons.
- ✅ Best choice:
formidable - Why? Mature, promise-based, and doesn’t care about your framework.
fastify.post('/upload', async (request, reply) => {
const { files } = await formidable().parse(request.raw);
// Process files
});
Scenario 4: Quick Prototype with Minimal Setup
You’re building a demo and just need files accessible immediately.
- ✅ Best choice:
express-fileupload - Why? One line of middleware, and files appear in
req.files.
app.use(fileUpload());
app.post('/demo', (req, res) => {
const buffer = req.files.demoFile.data;
// Use buffer right away
});
📌 Summary Table
| Package | Framework | Storage Default | Streaming? | Custom Storage? | Error Handling Style |
|---|---|---|---|---|---|
busboy | Any | None (you implement) | ✅ | ✅ | Event emitter |
express-fileupload | Express only | Memory (or temp file) | ❌ | Limited | Express error middleware |
formidable | Any | Temp disk file | ✅ | ✅ | Promise rejection / callback |
multer | Express only | Configurable | ❌ | ✅ (via engines) | Express error middleware |
💡 Final Thought
There’s no single “best” package — only the best fit for your constraints:
- Need maximum control and streaming? Go with
busboy. - Building a standard Express app with file uploads?
multeris the most polished choice. - Want simplicity in Express with minimal config?
express-fileuploadgets you there fastest. - Working outside Express but still want ease of use?
formidablestrikes a great balance.
Choose based on your stack, performance needs, and how much plumbing you’re willing to do yourself.
How to Choose: busboy vs express-fileupload vs formidable vs multer
- busboy:
Choose
busboyif you need a low-level, streaming parser that gives you full control over file handling without automatic disk writes. It’s ideal for building custom middleware, memory-efficient processing of large files, or integrating into non-Express frameworks. However, it requires more boilerplate code to manage streams and temporary storage. - express-fileupload:
Choose
express-fileuploadif you’re using Express and want a simple, zero-config way to access uploaded files viareq.files. It automatically buffers files in memory (or temp files for larger uploads) and exposes them as easy-to-use objects. Best suited for straightforward upload scenarios where you don’t need fine-grained control over the parsing pipeline. - formidable:
Choose
formidableif you prefer a standalone, framework-agnostic parser with a mature API that supports both callback and promise-based usage. It offers good configurability for file size limits, encoding, and storage behavior. While it works with Express, it doesn’t require it, making it a solid choice for Koa, Fastify, or vanilla Node.js servers. - multer:
Choose
multerif you’re building an Express application and need a robust, middleware-based solution with built-in support for disk storage, memory storage, and file filtering. It integrates seamlessly into Express routes, provides detailed file metadata, and handles common concerns like filename sanitization and size validation out of the box.
Popular Comparisons
README for busboy
Description
A node.js module for parsing incoming HTML form data.
Changes (breaking or otherwise) in v1.0.0 can be found here.
Requirements
- node.js -- v10.16.0 or newer
Install
npm install busboy
Examples
- Parsing (multipart) with default options:
const http = require('http');
const busboy = require('busboy');
http.createServer((req, res) => {
if (req.method === 'POST') {
console.log('POST request');
const bb = busboy({ headers: req.headers });
bb.on('file', (name, file, info) => {
const { filename, encoding, mimeType } = info;
console.log(
`File [${name}]: filename: %j, encoding: %j, mimeType: %j`,
filename,
encoding,
mimeType
);
file.on('data', (data) => {
console.log(`File [${name}] got ${data.length} bytes`);
}).on('close', () => {
console.log(`File [${name}] done`);
});
});
bb.on('field', (name, val, info) => {
console.log(`Field [${name}]: value: %j`, val);
});
bb.on('close', () => {
console.log('Done parsing form!');
res.writeHead(303, { Connection: 'close', Location: '/' });
res.end();
});
req.pipe(bb);
} else if (req.method === 'GET') {
res.writeHead(200, { Connection: 'close' });
res.end(`
<html>
<head></head>
<body>
<form method="POST" enctype="multipart/form-data">
<input type="file" name="filefield"><br />
<input type="text" name="textfield"><br />
<input type="submit">
</form>
</body>
</html>
`);
}
}).listen(8000, () => {
console.log('Listening for requests');
});
// Example output:
//
// Listening for requests
// < ... form submitted ... >
// POST request
// File [filefield]: filename: "logo.jpg", encoding: "binary", mime: "image/jpeg"
// File [filefield] got 11912 bytes
// Field [textfield]: value: "testing! :-)"
// File [filefield] done
// Done parsing form!
- Save all incoming files to disk:
const { randomFillSync } = require('crypto');
const fs = require('fs');
const http = require('http');
const os = require('os');
const path = require('path');
const busboy = require('busboy');
const random = (() => {
const buf = Buffer.alloc(16);
return () => randomFillSync(buf).toString('hex');
})();
http.createServer((req, res) => {
if (req.method === 'POST') {
const bb = busboy({ headers: req.headers });
bb.on('file', (name, file, info) => {
const saveTo = path.join(os.tmpdir(), `busboy-upload-${random()}`);
file.pipe(fs.createWriteStream(saveTo));
});
bb.on('close', () => {
res.writeHead(200, { 'Connection': 'close' });
res.end(`That's all folks!`);
});
req.pipe(bb);
return;
}
res.writeHead(404);
res.end();
}).listen(8000, () => {
console.log('Listening for requests');
});
API
Exports
busboy exports a single function:
( function )(< object >config) - Creates and returns a new Writable form parser stream.
-
Valid
configproperties:-
headers - object - These are the HTTP headers of the incoming request, which are used by individual parsers.
-
highWaterMark - integer - highWaterMark to use for the parser stream. Default: node's stream.Writable default.
-
fileHwm - integer - highWaterMark to use for individual file streams. Default: node's stream.Readable default.
-
defCharset - string - Default character set to use when one isn't defined. Default:
'utf8'. -
defParamCharset - string - For multipart forms, the default character set to use for values of part header parameters (e.g. filename) that are not extended parameters (that contain an explicit charset). Default:
'latin1'. -
preservePath - boolean - If paths in filenames from file parts in a
'multipart/form-data'request shall be preserved. Default:false. -
limits - object - Various limits on incoming data. Valid properties are:
-
fieldNameSize - integer - Max field name size (in bytes). Default:
100. -
fieldSize - integer - Max field value size (in bytes). Default:
1048576(1MB). -
fields - integer - Max number of non-file fields. Default:
Infinity. -
fileSize - integer - For multipart forms, the max file size (in bytes). Default:
Infinity. -
files - integer - For multipart forms, the max number of file fields. Default:
Infinity. -
parts - integer - For multipart forms, the max number of parts (fields + files). Default:
Infinity. -
headerPairs - integer - For multipart forms, the max number of header key-value pairs to parse. Default:
2000(same as node's http module).
-
-
This function can throw exceptions if there is something wrong with the values in config. For example, if the Content-Type in headers is missing entirely, is not a supported type, or is missing the boundary for 'multipart/form-data' requests.
(Special) Parser stream events
-
file(< string >name, < Readable >stream, < object >info) - Emitted for each new file found.
namecontains the form field name.streamis a Readable stream containing the file's data. No transformations/conversions (e.g. base64 to raw binary) are done on the file's data.infocontains the following properties:-
filename- string - If supplied, this contains the file's filename. WARNING: You should almost never use this value as-is (especially if you are usingpreservePath: truein yourconfig) as it could contain malicious input. You are better off generating your own (safe) filenames, or at the very least using a hash of the filename. -
encoding- string - The file's'Content-Transfer-Encoding'value. -
mimeType- string - The file's'Content-Type'value.
Note: If you listen for this event, you should always consume the
streamwhether you care about its contents or not (you can simply dostream.resume();if you want to discard/skip the contents), otherwise the'finish'/'close'event will never fire on the busboy parser stream. However, if you aren't accepting files, you can either simply not listen for the'file'event at all or setlimits.filesto0, and any/all files will be automatically skipped (these skipped files will still count towards any configuredlimits.filesandlimits.partslimits though).Note: If a configured
limits.fileSizelimit was reached for a file,streamwill both have a boolean propertytruncatedset totrue(best checked at the end of the stream) and emit a'limit'event to notify you when this happens. -
-
field(< string >name, < string >value, < object >info) - Emitted for each new non-file field found.
namecontains the form field name.valuecontains the string value of the field.infocontains the following properties:-
nameTruncated- boolean - Whethernamewas truncated or not (due to a configuredlimits.fieldNameSizelimit) -
valueTruncated- boolean - Whethervaluewas truncated or not (due to a configuredlimits.fieldSizelimit) -
encoding- string - The field's'Content-Transfer-Encoding'value. -
mimeType- string - The field's'Content-Type'value.
-
-
partsLimit() - Emitted when the configured
limits.partslimit has been reached. No more'file'or'field'events will be emitted. -
filesLimit() - Emitted when the configured
limits.fileslimit has been reached. No more'file'events will be emitted. -
fieldsLimit() - Emitted when the configured
limits.fieldslimit has been reached. No more'field'events will be emitted.