v4 preparations. Modern multipart form-data parser for Node.js, Bun, Deno, Cloudflare, and the
browser.
install
npm i formidable@next
Example
import { parseMultipartRequest, parseMultipart, formidableDefaultOptions, FormidableError, FormidableOptions, FormidablePart,} 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 (er: FormidableError) { switch (er.code) { case 'ERR_INVALID_INPUT': console.error(er.message); break; case 'ERR_BODY_CONSUMED': console.error(er.message); break; case 'ERR_FAILED_TO_PARSE_TEXT': console.error(er.message); break; case 'ERR_FAILED_TO_PARSE_JSON': console.error(er.message); break; case 'ERR_NO_BOUNDARY': console.error(er.message); break; case 'ERR_MAX_FILENAME_SIZE': console.error(er.message); break; case 'ERR_MAX_FILE_SIZE': console.error(er.message); break; case 'ERR_MAX_FILE_KEY_SIZE': console.error(er.message); break; case 'ERR_MAX_FIELD_SIZE': console.error(er.message); break; case 'ERR_MAX_FIELD_KEY_SIZE': console.error(er.message); break; case 'ERR_MAX_HEADER_SIZE': console.error(er.message); break; case 'ERR_MAX_HEADER_KEY_SIZE': console.error(er.message); break; case 'ERR_MAX_HEADER_VALUE_SIZE': console.error(er.message); break; case 'ERR_MAX_ALL_HEADERS_SIZE': console.error(er.message); break; } }}
Usage in Node.js v14 & v16
It bundles the web-streams-polyfill and headers-polyfill for compatibility with older Node.js
versions. For Node.js v14 it bundles both; for Node.js v16 it bundles only the
web-streams-polyfill.
for Node.js v14, you need to use the formidable/node14 import
for Node.js v16, you need to use the formidable/node16 import
import { createServer } from 'node:http';// import { parseMultipartRequest } from 'formidable/node14';import { parseMultipartRequest } from 'formidable/node16';// import { parseMultipartRequest } from 'formidable'; // modern node/bun/deno/cloudflareconst server = createServer((req, res) => { if (req.method === 'POST') { // considering the above `formidable` await parseMultipartRequest(req, { maxFileSize: 1 * 1024 * 1024 // 1mb, defaults to 100mb maxFilenameSize: 1000, // defaults to 255 maxFileKeySize: 1000, // defaults to 255 maxFieldKeySize: 1000, // defaults to 255 }, async
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