Object to FormData Serializer

Common errors

• TypeError: (0 , object_to_formdata__WEBPACK_IMPORTED_MODULE_0__.formData) is not a function

  cause Attempting to use the old `formData` named export after upgrading to version 4.0.0 or higher.
  fix The named export was renamed. Change `import { formData } from 'object-to-formdata';` to `import { serialize } from 'object-to-formdata';`.

• TypeError: object_to_formdata__WEBPACK_IMPORTED_MODULE_0__.default is not a function

  cause Attempting to import `object-to-formdata` as a default export, which was removed in version 3.0.0.
  fix The package no longer has a default export. Change `import serialize from 'object-to-formdata';` to `import { serialize } from 'object-to-formdata';`.

• FormData entries show '[object Object]' for nested objects or arrays instead of serialized keys.

  cause This is not an error but expected browser behavior. `FormData` itself flattens to key-value pairs where values are strings or `File`/`Blob` objects. Nested structures are flattened into keys like `parent[child]` or `array[0]`, not actual nested objects.
  fix The library correctly serializes nested objects and arrays into appropriate `FormData` keys. When inspecting `FormData` via `console.log`, you'll see the flattened key-value pairs, which is how HTTP `multipart/form-data` works. Ensure your backend is configured to parse these nested key structures (e.g., using a library like `multer` in Node.js).

Warnings

• breaking Starting with version 3.0.0, the package removed its default export. Attempts to import it using `import serialize from 'object-to-formdata'` will fail.
  Fix: Change your import statement to use named exports: `import { serialize } from 'object-to-formdata';`.
• breaking Version 4.0.0 introduced a breaking change by renaming the primary named export from `formData` to `serialize`.
  Fix: Update your import statement from `import { formData } from 'object-to-formdata';` to `import { serialize } from 'object-to-formdata';`.
• gotcha By default, boolean values (`true`/`false`) are serialized as the strings 'true'/'false'. If your backend expects integers (1/0), you need to configure this behavior.
  Fix: Set the `booleansAsIntegers` option to `true` in the configuration object: `serialize(object, { booleansAsIntegers: true })`.
• gotcha Arrays are serialized with bracket notation by default (e.g., `items[]`). If you need indexed keys (e.g., `items[0]`), or no array notation for files/attributes, specific options are required.
  Fix: Use the `indices: true` option for indexed array keys, or `noAttributesWithArrayNotation: true` / `noFilesWithArrayNotation: true` to suppress bracket notation for non-file/file attributes respectively.

Install

• npm install object-to-formdata npm
• yarn add object-to-formdata yarn
• pnpm add object-to-formdata pnpm

Imports

• serialize
  wrong:

  import serialize from 'object-to-formdata'; // incorrect since v3

  correct:

  import { serialize } from 'object-to-formdata';

  Since version 3.0.0, there is no default export. Version 4.0.0 changed the named export from `formData` to `serialize`.
• serialize (CommonJS)
  wrong:

  const serialize = require('object-to-formdata'); // incorrect since v3

  correct:

  const { serialize } = require('object-to-formdata');

  For CommonJS environments, ensure you destructure the `serialize` function as it's a named export.
• FormData (Type)

  import type { FormData } from 'object-to-formdata';

  The library ships with TypeScript types. While FormData is a global Web API, this might be used for specific internal types if exposed.

Quickstart

Demonstrates basic serialization of a complex JavaScript object, including files, arrays, and nested objects, into a FormData instance using various configuration options, and appending to existing FormData.

import { serialize } from 'object-to-formdata';

const userProfile = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  age: 30,
  isActive: true,
  roles: ['admin', 'editor'],
  address: {
    street: '123 Main St',
    city: 'Anytown',
    zip: '12345'
  },
  avatar: new File([''], 'avatar.png', { type: 'image/png' })
};

const options = {
  indices: true, // Serialize roles[0]=admin, roles[1]=editor
  booleansAsIntegers: true, // Serialize isActive=1
  nullsAsUndefineds: true, // Ignore null values
  dotsForObjectNotation: false // Use brackets for objects (address[street])
};

const formData = serialize(userProfile, options);

// To see the contents (FormData is not directly iterable by value without special methods):
for (const pair of formData.entries()) {
  console.log(`${pair[0]}: ${pair[1]}`);
}

// Example of appending to an existing FormData instance
const existingData = new FormData();
existingData.append('tenantId', '123-abc');
const combinedFormData = serialize({ metadata: 'important' }, {}, existingData);

for (const pair of combinedFormData.entries()) {
  console.log(`Combined: ${pair[0]}: ${pair[1]}`);
}