Connect Busboy Middleware

1.0.0 · maintenance · verified Wed Apr 22

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.

Common errors

```
TypeError: Cannot call method 'on' of undefined
```
cause 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.

Warnings

gotcha The `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`.
breaking connect-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.
gotcha connect-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.

Install

npm install connect-busboy npm
yarn add connect-busboy yarn
pnpm add connect-busboy pnpm

Imports

busboyMiddleware
wrong:
```
import busboyMiddleware from 'connect-busboy';
```
correct:
```
const busboyMiddleware = require('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
wrong:
```
import { Busboy } from 'connect-busboy';
```
correct:
```
const busboy = require('connect-busboy'); app.use(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`.

Quickstart

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}`);
});

view raw JSON →