form-data

form-data is a Node.js library for constructing readable multipart/form-data streams, the encoding browsers use to submit forms and file uploads. Its API is modeled on the XMLHttpRequest-2 FormData interface, so you append string, buffer, and stream values to a form and pipe or submit the result to any web application.

As one of the most-downloaded packages in the npm ecosystem, it is the standard building block behind file-upload support in HTTP clients like axios, node-fetch, and request. It handles boundary generation, content-type detection, content-length calculation, and header assembly so you can post files and mixed fields without hand-writing the multipart wire format.

What You Get

• A FormData class that streams multipart bodies without buffering entire files in memory
• Automatic boundary generation, content-type detection via mime-types, and content-length calculation
• A built-in submit() helper plus getHeaders()/getBuffer() for integration with axios, node-fetch, and request
• Hand-written TypeScript definitions (index.d.ts) for typed usage
• Per-part options for filename, filepath, content type, custom headers, and known length

Common Use Cases

• Uploading files from a Node.js backend to a third-party API or storage service
• Posting mixed form fields (strings, buffers, file streams) to an HTTP endpoint
• Providing the multipart body that HTTP clients such as axios and node-fetch send
• Streaming large files as upload parts without loading them fully into memory

Under The Hood

Architecture

The core is a single FormData class in lib/form_data.js (~500 lines) that inherits from combined-stream’s CombinedStream, making the form itself a readable stream. append() wraps each value with a generated multipart header and trailing line break and pushes it onto the combined stream, deferring stream reads until the consumer pulls data. Length bookkeeping is split between _overheadLength, _valueLength, and a _valuesToMeasure queue that getLength() resolves in parallel via asynckit, while submit() builds an http/https request from a URL or options object and pipes the form into it.

Tech Stack

Pure JavaScript (100% of the repo) targeting Node >= 6, with hand-written TypeScript definitions in index.d.ts. Runtime dependencies are minimal and focused: combined-stream for stream concatenation, asynckit for parallel length measurement, mime-types for content-type detection, plus hasown and es-set-tostringtag for safe property and tag handling. Tooling uses ESLint (ljharb config), istanbul for coverage, tape for tests, and browserify to produce the browser build declared via the browser field.

Code Quality

The library is mature and well-tested: 29 integration test files under test/integration plus static tests cover boundaries, custom headers, length calculation, submission variants, and streaming. The code carries JSDoc annotations and is security-conscious — escapeHeaderParam() escapes CR, LF, and quotes to block multipart header injection, backed by dedicated test-header-injection.js and test-boundary-prediction.js tests. Error handling surfaces length-calculation failures through callbacks rather than swallowing them.

API Design

The public API is deliberately small and familiar, mirroring the browser XMLHttpRequest-2 FormData interface: append(), getHeaders(), getBoundary(), getBuffer(), getLength(), and submit(). Getting started takes only a few lines, per-part options (filename, contentType, knownLength, custom headers) cover advanced cases, and the README documents integration recipes for axios, node-fetch, and request. Consistent naming and thorough docs keep the learning curve low.