Registry / web-framework / connect-busboy

connect-busboy

JSON →
library1.0.0jsnpmunverified

connect-busboy is a middleware for Node.js Connect and Express applications, designed to parse `multipart/form-data` requests, primarily for file uploads and complex form data. It acts as a wrapper around the powerful, streaming `busboy` parser, providing a simpler API for integration into the middleware stack. The current stable version is 1.0.0. The package has seen no updates in over four years (last published April 2022), indicating a maintenance-only status with a very slow release cadence. While it provides a straightforward way to handle multipart requests, more actively maintained alternatives like `multer` or `express-fileupload` are often preferred for modern Express applications due to ongoing support and feature development.

npm install connect-busboy
INSTALL
IMPORT
SIG · CONNECT-BUSBOY
C
connect-busboy
web-frameworkjavascriptv1.0.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.

busboyMiddleware
✓ const busboyMiddleware = require('connect-busboy');
✗ import busboyMiddleware from 'connect-busboy';
The package is primarily designed for CommonJS. While some bundlers might allow `import`, direct ESM usage is not officially supported or exemplified.
Busboy
✓ const busboy = require('connect-busboy'); app.use(busboy());
✗ import { Busboy } from 'connect-busboy';
The package exports a function, not a class or named export for Busboy itself. The function returns a middleware. The underlying Busboy instance is exposed via `req.busboy`.

This quickstart sets up an Express server to handle file uploads using connect-busboy, demonstrating how to configure middleware options, listen for file and field events, and save uploaded files to disk.

const express = require('express'); const busboy = require('connect-busboy'); const path = require('path'); const fs = require('fs'); const app = express(); // Default options, no immediate parsing app.use(busboy({ highWaterMark: 2 * 1024 * 1024, // Set file stream high water mark to 2MB limits: { fileSize: 10 * 1024 * 1024, // Limit uploaded file size to 10MB } })); app.get('/', (req, res) => { res.writeHead(200, { 'Connection': 'close' }); res.end(` <form method="POST" enctype="multipart/form-data"> <input type="file" name="uploadFile"><br/> <input type="text" name="description"><br/> <input type="submit" value="Upload"> </form> `); }); app.post('/', (req, res) => { if (!req.busboy) { return res.status(400).send('No busboy instance on request. Check headers and method.'); } req.busboy.on('file', (name, file, info) => { const { filename, encoding, mimeType } = info; console.log(`File [${name}]: filename: %j, encoding: %j, mimeType: %j`, filename, encoding, mimeType); const saveTo = path.join(__dirname, 'uploads', filename); console.log(`Saving file to: ${saveTo}`); file.pipe(fs.createWriteStream(saveTo)); file.on('end', () => { console.log(`File [${name}] finished`); }); }); req.busboy.on('field', (name, value, info) => { console.log(`Field [${name}]: value: %j`, value); }); req.busboy.on('finish', () => { console.log('Done parsing form!'); res.status(200).send('Upload successful!'); }); req.busboy.on('error', (err) => { console.error('Busboy error:', err); res.status(500).send('File upload failed.'); }); req.pipe(req.busboy); }); const PORT = process.env.PORT || 3000; // Ensure 'uploads' directory exists const uploadsDir = path.join(__dirname, 'uploads'); if (!fs.existsSync(uploadsDir)) { fs.mkdirSync(uploadsDir); } app.listen(PORT, () => { console.log(`Server listening on http://localhost:${PORT}`); });
Debug
Known issues
gotchaThe `connect-busboy` package has not been updated in over 4 years (last published April 2022), indicating very limited ongoing maintenance or bug fixes. Users should be aware that new features or patches for modern Node.js versions or potential security vulnerabilities are unlikely. Consider more actively maintained alternatives for new projects.
fix
For new projects or if active maintenance is crucial, consider alternatives like `multer` or `express-fileupload`.
affects: >=1.0.0
breakingconnect-busboy v1.0.0 depends on `busboy` ^1.0.0. The underlying `busboy` library introduced breaking changes in its v1.0.0 release (December 2021), which impact users of connect-busboy. These include: minimum Node.js version requirement changed to >=10.16.0; parameters passed to `file` and `field` event handlers are now consolidated into a single `info` object (containing `filename`, `encoding`, `mimeType`); and stricter header parsing for `multipart/form-data` requests.
fix
Ensure your Node.js version is >=10.16.0. Update event handler signatures for `file` and `field` events to destructure the `info` object for properties like `filename` and `mimeType` instead of separate arguments.
affects: >=1.0.0
gotchaconnect-busboy will only attach a `busboy` instance to `req.busboy` if specific conditions are met: the request method is not GET or HEAD, the `Content-Type` header is `application/x-www-form-urlencoded` or starts with `multipart/*`, and the `Content-Length` header is defined or chunked transfer encoding is in use. If `req.busboy` is `undefined`, these conditions were not met.
fix
Always check for `if (req.busboy)` before attempting to use it. Ensure client requests use appropriate HTTP methods (e.g., POST) and `Content-Type` headers for multipart data. Refer to the 'Troubleshooting' section in the package README.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot call method 'on' of undefined
The `req.busboy` object is undefined because the incoming HTTP request did not meet the criteria for connect-busboy to process it as multipart/form-data.
fix
Verify that the HTTP request method is not GET or HEAD, the 'Content-Type' header is set to 'multipart/form-data' or 'application/x-www-form-urlencoded', and 'Content-Length' is defined or chunked transfer encoding is used. Add a check `if (req.busboy) { ... }` before using it.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies
busboyrequiredCore library for parsing multipart/form-data requests. connect-busboy is a middleware wrapper around busboy.
connectoptionalconnect-busboy is designed as middleware for Connect-compatible frameworks like Connect and Express.
Agent activity
13 hits · last 30 days
node
10
Meta
2
OpenAI (training)
1
Resources
connect-busboy — npm install connect-busboy · libregistry