v4 preparations. Modern multipart form-data parser for Node.js, Bun, Deno, Cloudflare, and the
browser.
[!CAUTION]
For older Node versions like v14, v15 and v16 you have to use the web-streams-polyfill in your
project. Minimum required version is the first Node.js v14 LTS release, v14.15.0 (Fermium).
install
npm i formidable@next
Example
import { formidableDefaultOptions, FormidableError, FormidableOptions, FormidablePart, parseMultipart, parseMultipartRequest,} from 'formidable';async function formidable(req: Request, options?: FormidableOptions) { try { await parseMultipartRequest(req, options, async (part: FormidablePart) => { // part.type - part content type, media type (no charsets) // ==== Headers ==== // part.headers - part headers, parsed into type-safe SuperHeaders object // part.headers.contentType.mediaType - part content media type // part.headers.contentType.charset - part content charset // part.headers.contentDisposition.name // part.headers.contentDisposition.filename // part.headers.contentDisposition.preferredFilename // part.headers.contentDisposition.type - attachment or inline or form-data // ==== Streaming ==== // await part.stream() - no buffering, async iterable, useful to use in `for await (const chunk of part.stream())` // ==== Buffering ==== // await part.text(failSafe?) - buffer into string, pass failSafe = true to avoid crashing // await part.bytes() - buffer into Uint8Array bytes // await part.arrayBuffer() - buffer into ArrayBuffer // await part.json() - buffer into JSON object, pass failSafe = true to avoid crashing // ==== Utils ==== // part.toString() - string representing the state of properties (name, filename, type, headers) // part.toObject() - the core of `toString()`, returns an object with the properties (name, filename, type, headers) // part.isFile() - check if the part is a file if (part.isFile()) { console.log('file', part.name, part.filename, part.toString()); } else { // part.text() on field gets the input's value console.log('field', part.name, await part.text()); } }); } catch (err: FormidableError) { switch (err.code) { case 'ERR_INVALID_INPUT': { console.error(err.message); break; } case 'ERR_BODY_CONSUMED': { console.error(err.message); break; } case 'ERR_FAILED_TO_PARSE_TEXT': { console.error(err.message); break; } case 'ERR_FAILED_TO_PARSE_JSON': { console.error(err.message); break; } case 'ERR_NO_BOUNDARY': { console.error(err.message); break; } case 'ERR_MAX_FILENAME_SIZE': { console.error(err.message); break; } case 'ERR_MAX_FILE_SIZE': { console.error(err.message); break; } case 'ERR_MAX_FILE_KEY_SIZE': { console.error(err.message); break; } case 'ERR_MAX_FIELD_SIZE': { console.error(err.message); break; } case 'ERR_MAX_FIELD_KEY_SIZE': { console.error(err.message); break; } case 'ERR_MAX_HEADER_SIZE': { console.error(err.message); break; } case 'ERR_MAX_HEADER_KEY_SIZE': { console.error(err.message); break; } case 'ERR_MAX_HEADER_VALUE_SIZE': { console.error(err.message); break; } case 'ERR_MAX_ALL_HEADERS_SIZE': { console.error(err.message); break; } default: console.error('Unknown error:', err); break; } }}
Usage in Node.js v14 and v16
[!CAUTION]
Minimum required version is the first Node.js v14 LTS release, v14.15.0 (Fermium).
It bundles the headers-polyfill for compatibility with older Node.js versions. For Node.js v14 it
bundles both; for Node.js v16 you have to import 'web-streams-polyfill/polyfill'; for ESM, or
modules require('web-streams-polyfill/ponyfill'); for CJS
import 'web-streams-polyfill/polyfill';import { parseMultipartRequest } from 'formidable';import { createServer } from 'node:http';const server = createServer((req, res) => { if (req.method === 'POST') { // considering the above `formidable` await parseMultipartRequest( req, { maxFieldKeySize: 1000, // defaults to 255 maxFileKeySize: 1000, // defaults to 255 maxFilenameSize: 1000, // defaults to 255 maxFileSize: 1 * 1024 * 1024, // 1mb, defaults to 100mb
Usage in modern Node.js and other runtimes
You can either use the above helper formidable function or the parseMultipartRequest directly,
works on any Fetch/Request/Response API compatible runtime.
for Node.js v18+, you can use the formidable import directly
for Bun, Deno, Cloudflare, and the browser, you can use the formidable import too
// Deno/Bun/Cloudflareimport { parseMultipartRequest } from 'formidable';export default { async fetch(req: Request) { if (req.method === 'POST') { await parseMultipartRequest( req, { maxFieldKeySize: 1000, // defaults to 255 maxFileKeySize: 1000, // defaults to 255 maxFilenameSize: 1000, // defaults to 255 maxFileSize: 1 * 1024 * 1024, // 1mb, defaults to 100mb }, async (part: FormidablePart) =>
Options
maxAllHeadersSize{number} - size for all headers combined, (default: 8kb)
maxHeaderKeySize{number} - size of the key per each header, (default: 255)
maxHeaderValueSize{number} - size of the value of each header, (default: 1kb)
maxHeaderSize{number} - size of key + value of each header, (default: 2kb)
maxFilenameSize{number} - size of the file original filename, (default: 255)
maxFileKeySize{number} - size of the key of file fields, (default: 255)
maxFileSize{number} - size of each file, (default: 100mb)
maxFieldKeySize{number} - size of the key of text fields, (default: 255)
maxFieldSize{number} - size of each text field value, (default: 100kb)