HTML5 FormData Polyfill for Browsers and Node.js

Common errors

• ReferenceError: FormData is not defined

  cause In Node.js, attempting to use `FormData` without correctly importing the ESM module, or using CommonJS `require` directly on `formdata-polyfill/esm.min.js`.
  fix For 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

  cause 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`.
  fix Explicitly 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)

  cause 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.
  fix Upgrade your Node.js environment to version `12.20.0` or higher to meet the package's engine requirements.

Warnings

• breaking Prior 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.
  Fix: Review 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.
• gotcha When 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.
  Fix: Always convert `FormData` to a `Blob` when constructing `Request` or `Response` objects: `new Request(url, { body: fd._blob ? fd._blob() : fd })`.
• gotcha The 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.
  Fix: Ensure your Node.js environment is updated to version `12.20.0` or higher to meet the package's engine requirements.
• gotcha The 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.
  Fix: Thoroughly 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.

Install

• npm install formdata-polyfill npm
• yarn add formdata-polyfill yarn
• pnpm add formdata-polyfill pnpm

Imports

• FormData
  wrong:

  const FormData = require('formdata-polyfill');

  correct:

  import { FormData } from 'formdata-polyfill/esm.min.js';

  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
  wrong:

  import formDataToBlob from 'formdata-polyfill/esm.min.js';

  correct:

  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)
  wrong:

  import { FormData } from 'formdata-polyfill';

  correct:

  import '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.

Quickstart

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();