Registry / http-networking / busboy

busboy

JSON →
library1.6.0jsnpmunverified

Busboy is a high-performance, streaming parser for incoming HTML form data in Node.js, specifically designed to handle `multipart/form-data` and `application/x-www-form-urlencoded` request bodies. As of version 1.6.0, it provides a lightweight and memory-efficient solution for processing file uploads and form fields by emitting events as data streams in, rather than buffering the entire request. Its event-driven API grants developers fine-grained control over how incoming data is managed, making it suitable for integration with various storage solutions or processing pipelines. While a precise release cadence isn't publicly defined, the project appears actively maintained. Busboy differentiates itself by focusing purely on parsing the raw input stream without making assumptions about how the parsed data should be stored or handled, leaving those decisions entirely to the application developer. It requires Node.js v10.16.0 or newer.

http-networkingweb-framework
npm install busboy
github ↗package ↗
INSTALL
IMPORT
SIG · BUSBOY
B
busboy
http-networkingjavascriptv1.6.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

busboy (function)
✓ const busboy = require('busboy');
✗ import busboy from 'busboy';
Busboy is primarily a CommonJS module. Direct ESM `import` statements may not work as expected without a transpiler or ESM wrapper due to its `module.exports = function` structure.
Busboy instance (returned stream)
✓ const bb = busboy({ headers: req.headers });
✗ const bb = new busboy({ headers: req.headers });
Since v1.0.0, `busboy` is a function that returns a Writable stream, not a constructor. Attempting to use `new` will result in a TypeError.
Named import (for CJS module)
✓ const busboy = require('busboy');
✗ import { busboy } from 'busboy';
Even if an ESM loader were used for CJS, `busboy` exports a default function, not named exports. Named imports will fail.

This example sets up a basic HTTP server that uses Busboy to parse multipart/form-data POST requests. It demonstrates how to listen for 'file' and 'field' events to process incoming file uploads and regular form fields, logging their details and data lengths.

const http = require('http'); const busboy = require('busboy'); const port = process.env.PORT ?? 8000; http.createServer((req, res) => { if (req.method === 'POST') { console.log('POST request received'); 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, { 'Content-Type': 'text/html', Connection: 'close' }); res.end(` <html> <head><title>Upload Form</title></head> <body> <form method="POST" enctype="multipart/form-data"> <input type="file" name="filefield"><br /> <input type="text" name="textfield"><br /> <input type="submit" value="Upload"> </form> </body> </html> `); } }).listen(port, () => { console.log(`Listening for requests on http://localhost:${port}`); });
Debug
Known issues
breakingBusboy v1.0.0 introduced significant breaking changes, primarily altering its API surface. The main export changed from a constructor (`new Busboy()`) to a function (`busboy()`) that returns a parser stream.
fix
Migrate `new Busboy(...)` calls to `busboy(...)`. Review event signatures for 'file' and 'field' events, as their arguments were consolidated into an `info` object. Additionally, the default for `preservePath` changed to `false` for multipart files.
affects: >=1.0.0
breakingThe `file` and `field` event signatures were changed in v1.0.0 to consolidate metadata into an `info` object. Direct access to arguments like `filename` or `fieldnameTruncated` as separate parameters is no longer supported.
fix
For `file` events, instead of `(name, file, filename, encoding, mimetype)`, use `(name, file, info)` and access properties like `info.filename`. For `field` events, instead of `(name, val, fieldnameTruncated, valTruncated, encoding, mimetype)`, use `(name, val, info)` and access properties like `info.nameTruncated`.
affects: >=1.0.0
gotchaBusboy is a streaming parser, meaning it does not buffer entire files or fields by default. This requires careful handling of the 'file' stream to prevent backpressure issues or resource leaks if the stream is not consumed or piped.
fix
Always attach 'data' and 'end'/'close' listeners to the `file` stream, or pipe it to a destination (e.g., `fs.createWriteStream`). If a file stream is not consumed, ensure `file.resume()` is called to prevent the parser from stalling.
affects: >=0.1.0
gotchaWhen saving uploaded files to disk, directly using `info.filename` (from the `file` event) can expose your server to path traversal vulnerabilities if not properly sanitized.
fix
Always sanitize `info.filename` before using it to construct a file path. Use a library like `path.basename()` or implement a robust sanitation method to ensure the path does not escape the intended directory. For example, `path.join(uploadDir, path.basename(info.filename))`.
affects: >=0.1.0
gotchaBusboy does not enforce limits on file sizes or the number of fields/files by default, which can lead to Denial of Service (DoS) attacks through memory exhaustion if not configured.
fix
Configure `limits` in the Busboy options, such as `limits: { fileSize: 10 * 1024 * 1024, files: 5, fields: 10 }` to restrict maximum file size, number of files, and number of fields, respectively. Also, implement timeouts for inactive connections.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: busboy is not a constructor
Attempting to instantiate Busboy using `new busboy()` instead of calling it as a function.
fix
Remove the `new` keyword: `const bb = busboy({ headers: req.headers });`
Error: Cannot find module 'busboy'
The 'busboy' package is not installed or the Node.js runtime cannot locate it.
fix
Ensure the package is installed in your project: `npm install busboy` or `yarn add busboy`.
SyntaxError: Named export 'busboy' not found (import { busboy } from 'busboy')
Attempting to use ESM named import syntax for a CommonJS module that exports a default function.
fix
Use the CommonJS `require` syntax: `const busboy = require('busboy');`
Upgrade
Version history
1.6.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
24 hits · last 30 days
node
22
OpenAI (training)
1
Resources
githubhttps://github.com/mscdex/busboy ↗
packagehttps://www.npmjs.com/package/busboy ↗
busboy — npm install busboy · libregistry