Express Formidable Middleware

1.2.0 verified Thu Apr 23 auth: no javascript abandoned

express-formidable is an Express.js middleware designed to simplify parsing of various form data types, including `application/x-www-form-urlencoded`, `application/json`, and notably `multipart/form-data` for file uploads. It acts as a bridge, wrapping the core `formidable` Node.js module to integrate its parsing capabilities directly into the Express request-response cycle, populating `req.fields` for non-file data and `req.files` for uploaded files. The package's current stable version is 1.2.0, which was last published over seven years ago. Due to this prolonged inactivity, the project is considered abandoned, with no ongoing maintenance or updates. This lack of development means it does not support modern JavaScript features like ESM out-of-the-box and is unlikely to be compatible with recent major versions of Express or `formidable`. Developers looking for robust form data parsing, especially with file uploads, should consider actively maintained alternatives like `multer` or directly using the latest versions of `formidable` with explicit Express integration, or the community-maintained `express-formidable-v2`.

Common errors

error TypeError: app.use() requires middleware functions but got a [object Undefined] ↓

cause Attempting to use `express-formidable` without correctly requiring the module, or if the module fails to load.

fix

Ensure const formidableMiddleware = require('express-formidable'); is correct and the package is installed. Verify the environment is CommonJS.

error Request hangs indefinitely / `req.fields` and `req.files` are undefined or empty ↓

cause Another middleware (e.g., `express.json()` or `body-parser`) has already consumed the request stream before `express-formidable` could process it, or the middleware is not properly applied to the route.

fix

Remove or selectively apply other body parsing middleware. express-formidable should be used as the primary body parser for routes handling multipart/form-data. Ensure app.use(formidableMiddleware()) is called before any routes that expect to use it.

Warnings

breaking The `express-formidable` package is abandoned and has not been updated in over seven years. It lacks support for modern Node.js versions, ECMAScript modules (ESM), and recent breaking changes in Express.js or the underlying `formidable` library. It is strongly advised to use actively maintained alternatives like `multer` or `formidable` directly. ↓

fix Migrate to `multer` or directly integrate `formidable` (latest version) with Express.js, using `express-formidable-v2` as a drop-in replacement if direct migration is not feasible.

gotcha Using `express-formidable` concurrently with `body-parser` middleware (e.g., `app.use(express.json())` or `app.use(express.urlencoded())`) will cause issues, as both attempt to consume the incoming request stream. This can lead to requests hanging or form data not being parsed correctly. ↓

fix Ensure `express-formidable` is the only middleware responsible for parsing form data on routes where file uploads or complex form data are expected. Do not apply `express.json()` or `express.urlencoded()` to these specific routes or globally before `express-formidable`.

breaking The package only explicitly supports Node.js versions `>=8`. Using it with significantly newer Node.js versions (e.g., Node.js 16+) may lead to unexpected behavior or compatibility issues due to underlying API changes in Node.js core or dependencies over time. ↓

fix Upgrade to a modern, maintained form parsing library that explicitly supports your current Node.js version.

gotcha The package is CommonJS-only and does not provide ECMAScript Module (ESM) exports. Attempting to `import expressFormidable from 'express-formidable'` in an ESM context will result in a runtime error. ↓

fix For ESM projects, consider alternatives. If you must use it, it might require a CommonJS wrapper or bundler configuration, but this is not recommended given its abandoned status.

Install

npm install express-formidable

yarn add express-formidable

pnpm add express-formidable

Imports

expressFormidable

wrong

import expressFormidable from 'express-formidable';

correct

const expressFormidable = require('express-formidable');

The package is CommonJS-only and does not provide ESM exports. Use `require`.

FormidableMiddleware

wrong

import { FormidableMiddleware } from 'express-formidable';

correct

import ExpressFormidable from 'express-formidable';
// For TypeScript type declarations
import { Fields, Files } from 'formidable';
declare global { namespace Express { interface Request { fields?: Fields; files?: Files; } } }

TypeScript types are available via `@types/express-formidable` and extend the `Express.Request` object, but the package itself has no named exports.

Quickstart

This example demonstrates a basic Express server using express-formidable to handle file uploads and form fields via a POST request.

const express = require('express');
const formidableMiddleware = require('express-formidable');

const app = express();
const PORT = process.env.PORT || 3000;

// Apply the formidable middleware
app.use(formidableMiddleware({
  uploadDir: './uploads', // Specify upload directory (must exist)
  keepExtensions: true,
  multiples: true // Allow multiple files for the same field name
}));

// Create an endpoint to handle file uploads
app.post('/upload', (req, res) => {
  console.log('Received upload request.');
  console.log('Fields:', req.fields); // Non-file fields
  console.log('Files:', req.files);   // Uploaded files

  if (req.files && Object.keys(req.files).length > 0) {
    res.status(200).send('File(s) uploaded successfully!');
  } else {
    res.status(400).send('No files were uploaded or an error occurred.');
  }
});

// A simple GET endpoint to show it works
app.get('/', (req, res) => {
  res.status(200).send('<h1>Upload Service</h1><form action="/upload" method="post" enctype="multipart/form-data"><input type="file" name="myFile" multiple><input type="text" name="description"><button type="submit">Upload</button></form>');
});

app.listen(PORT, () => {
  console.log(`Server listening on http://localhost:${PORT}`);
  console.log('Ensure `./uploads` directory exists.');
});