Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FormData
✓ import { FormData } from 'formdata-polyfill/esm.min.js';
✗ const FormData = require('formdata-polyfill');
For Node.js, the `FormData` class is exposed as a named export from the ESM build. The package's main entry point for CommonJS provides the browser polyfill, not the Node.js module.
formDataToBlob
✓ import { formDataToBlob } from 'formdata-polyfill/esm.min.js';
✗ import formDataToBlob from 'formdata-polyfill/esm.min.js';
The `formDataToBlob` utility is a named export from the ESM build, designed for converting FormData instances into Blobs.
Polyfill activation (browser)
✓ import 'formdata-polyfill';
✗ import { FormData } from 'formdata-polyfill';
To activate the polyfill in a browser environment, simply import the package's side effects. This patches the global `FormData` and related APIs.
This quickstart demonstrates creating `FormData` instances in Node.js, appending various data types including files and stream-like objects, and sending them via `fetch`. It also shows how to convert `FormData` to a `Blob` using `formDataToBlob` and send the resulting `Blob`.
import fetch from 'node-fetch';
import File from 'fetch-blob/file.js';
import { fileFromSync } from 'fetch-blob/from.js';
import { FormData, formDataToBlob } from 'formdata-polyfill/esm.min.js';
import { Readable } from 'node:stream';
import fs from 'node:fs';
// Create a dummy README.md for the quickstart if it doesn't exist
if (!fs.existsSync('./README.md')) {
fs.writeFileSync('./README.md', '# Quickstart Test\nThis is a test file for the formdata-polyfill quickstart.');
}
async function runQuickstart() {
console.log('--- FormData with fetch ---');
const filePath = './README.md';
const file = fileFromSync(filePath);
const fd = new FormData();
fd.append('file-upload-simple', new File(['abc'], 'hello-world.txt', { type: 'text/plain' }));
fd.append('file-upload-readme', file, 'quickstart-readme.md');
// It's also possible to append file/blob look-a-like items
// if you have streams coming from other destinations
const dummyStream = Readable.from(['part1', 'part2', 'part3']);
fd.append('file-upload-stream', {
size: 123,
type: 'video/mp4',
name: 'cat-video.mp4',
stream() { return dummyStream; },
[Symbol.toStringTag]: 'File'
}, 'cat-video.mp4');
try {
const response = await fetch('https://httpbin.org/post', { method: 'POST', body: fd });
const data = await response.json();
console.log('FormData fetch response:', data.files || data.form || data.data);
} catch (error) {
console.error('Error during FormData fetch:', error.message);
}
console.log('\n--- FormData converted to Blob with fetch ---');
const anotherFd = new FormData();
anotherFd.append('text', 'Hello Blob!');
anotherFd.append('image', new File(['image data'], 'my-image.png', { type: 'image/png' }));
const blob = formDataToBlob(anotherFd);
console.log('Generated Blob:', { size: blob.size, type: blob.type });
try {
const response = await fetch('https://httpbin.org/post', {
method: 'POST',
body: blob,
headers: {
'Content-Type': blob.type,
'Content-Length': blob.size
}
});
const data = await response.json();
console.log('Blob fetch response (parts of form data might be in `data` or `json` fields for httpbin):', data.data || data.json || data);
} catch (error) {
console.error('Error during Blob fetch:', error.message);
}
}
runQuickstart();
Debug
Known issues
breakingPrior to version 3.x, the browser polyfill did not globally replace the native `FormData` implementation, requiring manual instantiation or explicit patching. Upgrading to 3.x and above automatically replaces the global `FormData`, simplifying usage but potentially causing conflicts if other libraries expected a specific native `FormData` instance or attempted their own patching.fixReview existing code for explicit `FormData` instantiation or custom polyfill logic when upgrading from 2.x to 3.x+. Remove any custom `FormData` shims or polyfills, as this package now handles global replacement.
affects: <3.0.0
gotchaWhen using the browser polyfill, direct passing of a `FormData` instance to the `body` option of `new Request()` or `new Response()` constructors is not fully supported due to limitations in patching native constructors. Developers must explicitly call `fd._blob()` on the `FormData` instance to serialize it into a `Blob` before passing it to the constructor.fixAlways convert `FormData` to a `Blob` when constructing `Request` or `Response` objects: `new Request(url, { body: fd._blob ? fd._blob() : fd })`. affects: >=3.0.0
gotchaThe Node.js ESM version (`formdata-polyfill/esm.min.js`) has higher platform dependencies, specifically requiring Node.js version `12.20.0` or higher. This is due to its reliance on modern JavaScript features like classes, symbols, and private fields. Using it with older Node.js versions will result in syntax errors during module loading.fixEnsure your Node.js environment is updated to version `12.20.0` or higher to meet the package's engine requirements.
affects: <12.20.0 (Node.js)
gotchaThe browser polyfill deeply patches global objects and prototypes such as `XMLHttpRequest.prototype.send`, the global `fetch` function, and `navigator.sendBeacon`. This extensive patching can lead to unforeseen conflicts or unexpected behavior if other libraries or polyfills attempt to modify the same native APIs, requiring careful testing in complex front-end environments.fixThoroughly test `formdata-polyfill` in environments with other polyfills or libraries that modify native browser APIs. If conflicts arise, consider loading `formdata-polyfill` early or investigating alternative `FormData` solutions.
affects: >=3.0.0
Errors
Common errors & fixes
ReferenceError: FormData is not defined
In Node.js, attempting to use `FormData` without correctly importing the ESM module, or using CommonJS `require` directly on `formdata-polyfill/esm.min.js`.
fixFor Node.js, ensure you are using ES Modules and import explicitly: `import { FormData } from 'formdata-polyfill/esm.min.js;'` TypeError: fd._blob is not a function
Trying to pass a `FormData` instance directly to the `body` of `new Request()` or `new Response()` in a browser environment where the polyfill is active, without manually converting it to a `Blob`.
fixExplicitly convert the `FormData` to a `Blob` using `fd._blob()`: `new Request(url, { method: 'post', body: fd._blob ? fd._blob() : fd })`. SyntaxError: Unexpected token 'class' (or similar ESNext syntax error on module load)
Running the Node.js ESM module on an unsupported Node.js version, below `12.20.0`, which lacks support for modern JavaScript features used by the package.
fixUpgrade your Node.js environment to version `12.20.0` or higher to meet the package's engine requirements.
Audit
Dependencies
fetch-blobrequiredCore dependency for Blob and File handling in Node.js environments.
node-fetchoptionalCommonly used with `formdata-polyfill` in Node.js for making network requests. While not a direct dependency, it's a primary integration target.