formidable — Fast Streaming Multipart Form Parser for Node.js

Introduction

formidable is a streaming multipart form data parser for Node.js. It handles file uploads efficiently by writing incoming data directly to disk or a custom destination as it arrives, rather than buffering entire files in memory. Originally created in 2010 by Felix Geisendorfer, it remains one of the most downloaded file upload parsers in the Node.js ecosystem.

What formidable Does

• Parses multipart/form-data requests for file uploads
• Parses application/x-www-form-urlencoded and JSON request bodies
• Streams uploaded files directly to disk to minimize memory usage
• Provides progress events for upload monitoring
• Supports pluggable file storage backends

Architecture Overview

formidable uses a streaming state machine to parse incoming HTTP request bodies. As data chunks arrive, the parser identifies multipart boundaries, extracts headers, and routes file content to writable streams. This architecture means a 1 GB upload never occupies more than a few kilobytes of memory. The parser emits events for each field, file start, file end, and progress update. A plugin system allows replacing the default file writer with custom backends like cloud storage.

Self-Hosting & Configuration

• Install via npm: npm install formidable
• Set upload directory: formidable({ uploadDir: '/tmp/uploads' })
• Limit file size: formidable({ maxFileSize: 10 * 1024 * 1024 }) for 10 MB
• Allow multiple files per field: formidable({ multiples: true })
• Use with Express: wrap in middleware or call form.parse(req) inside a route handler

Key Features

• Streaming parser with minimal memory footprint even for large uploads
• Built-in support for multipart, urlencoded, and JSON content types
• File size and field count limits to prevent abuse
• Upload progress events for building progress bars
• Pluggable file handling for custom storage destinations

Comparison with Similar Tools

• multer — Express-specific middleware; formidable works with any Node.js HTTP server
• busboy — lower-level streaming parser; formidable adds file management and a higher-level API
• multiparty — similar streaming approach; formidable has broader adoption and active maintenance
• express-fileupload — simpler API but buffers files in memory; formidable streams to disk by default

FAQ

Q: Does formidable work with Express? A: Yes. Call form.parse(req) inside an Express route handler. It does not require Express-specific middleware.

Q: How do I limit upload file size? A: Set maxFileSize in the options: formidable({ maxFileSize: 5 * 1024 * 1024 }) for a 5 MB limit.

Q: Can I upload files to cloud storage instead of disk? A: Yes. Use the plugin system or handle the fileBegin event to pipe file data to a cloud storage SDK stream.

Q: Does it support multiple file uploads in a single field? A: Yes. Enable with formidable({ multiples: true }). Files arrive as an array in the parsed result.

Sources

• https://github.com/node-formidable/formidable
• https://github.com/node-formidable/formidable/blob/master/README.md