@fastify/busboy
Advanced tools
The @fastify/busboy package is a plugin for the Fastify web framework. It is primarily used for handling multipart/form-data, which is often used for uploading files through HTTP forms. It wraps the busboy library, providing an easy-to-use interface for parsing form submissions, especially file uploads, within Fastify applications.
File Upload
This feature allows for handling file uploads in a Fastify application. The code demonstrates how to register the @fastify/busboy plugin and set up a route to handle POST requests for file uploads. The multipart method is used to process the incoming file stream.
fastify.register(require('@fastify/busboy'));
fastify.post('/upload', function (req, reply) {
const mp = req.multipart(handler, function (err) {
console.log('upload completed');
reply.code(200).send();
});
function handler (field, file, filename, encoding, mimetype) {
// Perform actions with the file stream
}
});Field Parsing
This feature is used for parsing non-file fields from a multipart/form-data request. The example shows how to collect form fields into an object and handle the form parsing completion.
fastify.register(require('@fastify/busboy'));
fastify.post('/form', function (req, reply) {
const data = {};
const mp = req.multipart(function (field, value) {
data[field] = value;
}, function (err) {
console.log('form parsing completed', data);
reply.code(200).send(data);
}, { limits: { fields: 5 } });
});Multer is a node.js middleware for handling multipart/form-data, which is primarily used for uploading files. It is very similar to @fastify/busboy but is designed for use with Express.js rather than Fastify. Multer provides a rich set of features for file upload handling and is widely used in the Express community.
Formidable is a Node.js module for parsing form data, especially file uploads. It can be used with any web framework, making it more flexible than @fastify/busboy in terms of compatibility. Formidable supports file uploads, including multiple files, and provides a lower-level API for handling form data.
A Node.js module for parsing incoming HTML form data.
This is an officially supported fork by fastify organization of the amazing library originally created by Brian White, aimed at addressing long-standing issues with it.
Benchmark (Mean time for 500 Kb payload, 2000 cycles, 1000 cycle warmup):
| Library | Version | Mean time in nanoseconds (less is better) |
|---|---|---|
| busboy | 0.3.1 | 340114 |
| @fastify/busboy | 1.0.0 | 270984 |
Changelog since busboy 0.31.
npm i @fastify/busboy
const http = require('node:http');
const { inspect } = require('node:util');
const Busboy = require('@fastify/busboy');
http.createServer((req, res) => {
if (req.method === 'POST') {
const busboy = new Busboy({ headers: req.headers });
busboy.on('file', (fieldname, file, filename, encoding, mimetype) => {
console.log(`File [${fieldname}]: filename: ${filename}, encoding: ${encoding}, mimetype: ${mimetype}`);
file.on('data', data => {
console.log(`File [${fieldname}] got ${data.length} bytes`);
});
file.on('end', () => {
console.log(`File [${fieldname}] Finished`);
});
});
busboy.on('field', (fieldname, val, fieldnameTruncated, valTruncated, encoding, mimetype) => {
console.log(`Field [${fieldname}]: value: ${inspect(val)}`);
});
busboy.on('finish', () => {
console.log('Done parsing form!');
res.writeHead(303, { Connection: 'close', Location: '/' });
res.end();
});
req.pipe(busboy);
} 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="text" name="textfield"><br>
<input type="file" name="filefield"><br>
<input type="submit">
</form>
</body></html>`);
}
}).listen(8000, () => {
console.log('Listening for requests');
});
// Example output, using http://nodejs.org/images/ryan-speaker.jpg as the file:
//
// Listening for requests
// File [filefield]: filename: ryan-speaker.jpg, encoding: binary
// File [filefield] got 11971 bytes
// Field [textfield]: value: 'testing! :-)'
// File [filefield] Finished
// Done parsing form!
const http = require('node:http');
const path = require('node:path');
const os = require('node:os');
const fs = require('node:fs');
const Busboy = require('@fastify/busboy');
http.createServer(function(req, res) {
if (req.method === 'POST') {
const busboy = new Busboy({ headers: req.headers });
busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
var saveTo = path.join(os.tmpdir(), path.basename(fieldname));
file.pipe(fs.createWriteStream(saveTo));
});
busboy.on('finish', function() {
res.writeHead(200, { 'Connection': 'close' });
res.end("That's all folks!");
});
return req.pipe(busboy);
}
res.writeHead(404);
res.end();
}).listen(8000, function() {
console.log('Listening for requests');
});
const http = require('node:http');
const { inspect } = require('node:util');
const Busboy = require('@fastify/busboy');
http.createServer(function(req, res) {
if (req.method === 'POST') {
const busboy = new Busboy({ headers: req.headers });
busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
console.log('File [' + fieldname + ']: filename: ' + filename);
file.on('data', function(data) {
console.log('File [' + fieldname + '] got ' + data.length + ' bytes');
});
file.on('end', function() {
console.log('File [' + fieldname + '] Finished');
});
});
busboy.on('field', function(fieldname, val, fieldnameTruncated, valTruncated) {
console.log('Field [' + fieldname + ']: value: ' + inspect(val));
});
busboy.on('finish', function() {
console.log('Done parsing form!');
res.writeHead(303, { Connection: 'close', Location: '/' });
res.end();
});
req.pipe(busboy);
} else if (req.method === 'GET') {
res.writeHead(200, { Connection: 'close' });
res.end('<html><head></head><body>\
<form method="POST">\
<input type="text" name="textfield"><br />\
<select name="selectfield">\
<option value="1">1</option>\
<option value="10">10</option>\
<option value="100">100</option>\
<option value="9001">9001</option>\
</select><br />\
<input type="checkbox" name="checkfield">Node.js rules!<br />\
<input type="submit">\
</form>\
</body></html>');
}
}).listen(8000, function() {
console.log('Listening for requests');
});
// Example output:
//
// Listening for requests
// Field [textfield]: value: 'testing! :-)'
// Field [selectfield]: value: '9001'
// Field [checkfield]: value: 'on'
// Done parsing form!
Busboy is a Writable stream
file(< string >fieldname, < ReadableStream >stream, < string >filename, < string >transferEncoding, < string >mimeType) - Emitted for each new file form field found. transferEncoding contains the 'Content-Transfer-Encoding' value for the file stream. mimeType contains the 'Content-Type' value for the file stream.
stream no matter if you care about the file contents or not (e.g. you can simply just do stream.resume(); if you want to discard the contents), otherwise the 'finish' event will never fire on the Busboy instance. However, if you don't care about any incoming files, you can simply not listen for the 'file' event at all and any/all files will be automatically and safely discarded (these discarded files do still count towards files and parts limits).stream will both have a boolean property truncated (best checked at the end of the stream) and emit a 'limit' event to notify you when this happens.bytesRead informs about the number of bytes that have been read so far.field(< string >fieldname, < string >value, < boolean >fieldnameTruncated, < boolean >valueTruncated, < string >transferEncoding, < string >mimeType) - Emitted for each new non-file field found.
partsLimit() - Emitted when specified parts limit has been reached. No more 'file' or 'field' events will be emitted.
filesLimit() - Emitted when specified files limit has been reached. No more 'file' events will be emitted.
fieldsLimit() - Emitted when specified fields limit has been reached. No more 'field' events will be emitted.
(constructor)(< object >config) - Creates and returns a new Busboy instance.
The constructor takes the following valid config settings:
headers - object - These are the HTTP headers of the incoming request, which are used by individual parsers.
autoDestroy - boolean - Whether this stream should automatically call .destroy() on itself after ending. (Default: false).
highWaterMark - integer - highWaterMark to use for this Busboy instance (Default: WritableStream default).
fileHwm - integer - highWaterMark to use for file streams (Default: ReadableStream default).
defCharset - string - Default character set to use when one isn't defined (Default: 'utf8').
preservePath - boolean - If paths in the multipart 'filename' field shall be preserved. (Default: false).
isPartAFile - function - Use this function to override the default file detection functionality. It has following parameters:
fieldName - string The name of the field.
contentType - string The content-type of the part, e.g. text/plain, image/jpeg, application/octet-stream
fileName - string The name of a file supplied by the part.
(Default: (fieldName, contentType, fileName) => (contentType === 'application/octet-stream' || fileName !== undefined))
limits - object - Various limits on incoming data. Valid properties are:
fieldNameSize - integer - Max field name size (in bytes) (Default: 100 bytes).
fieldSize - integer - Max field value size (in bytes) (Default: 1 MiB, which is 1024 x 1024 bytes).
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
headerSize - integer - For multipart forms, the max size of a multipart header Default: 81920.
The constructor can throw errors:
Busboy expected an options-Object. - Busboy expected an Object as first parameters.
Busboy expected an options-Object with headers-attribute. - The first parameter is lacking of a headers-attribute.
Limit $limit is not a valid number - Busboy expected the desired limit to be of type number. Busboy throws this Error to prevent a potential security issue by falling silently back to the Busboy-defaults. Potential source for this Error can be the direct use of environment variables without transforming them to the type number.
Unsupported Content-Type. - The Content-Type isn't one Busboy can parse.
Missing Content-Type-header. - The provided headers don't include Content-Type at all.
FAQs
A streaming parser for HTML form data for node.js
The npm package @fastify/busboy receives a total of 11,360,756 weekly downloads. As such, @fastify/busboy popularity was classified as popular.
We found that @fastify/busboy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket identified 80 fake candidates targeting engineering roles, including suspected North Korean operators, exposing the new reality of hiring as a security function.
Application Security
/Research
/Security News
Socket detected multiple compromised CrowdStrike npm packages, continuing the "Shai-Hulud" supply chain attack that has now impacted nearly 500 packages.
Research
/Security News
Malicious update to @ctrl/tinycolor on npm is part of a supply-chain attack hitting 40+ packages across maintainers