# formstream

> A multipart/form-data encoded stream, helper for file upload.

Latest version **1.5.2** (published 2025-07-29) · MIT license · 513.4K weekly downloads

## Install

```sh
npm install formstream
pnpm add formstream
yarn add formstream
bun add formstream
```

## Health

**Score 55/100 (C)** — status: maintenance-mode.

Positive: moderate downloads; has types; no vulnerabilities; has provenance; high quality score.

Warnings: no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.2 |
| Published | 2025-07-29 |
| First published | 2012-10-11 |
| Weekly downloads | 513.4K |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 20.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 144 |
| Author | fengmk2 |
| Maintainers | dead_horse, fengmk2 |
| Keywords | form, stream, multipart, form-data, upload, postfile, request |

## Links

- npm: https://www.npmjs.com/package/formstream
- Repository: https://github.com/node-modules/formstream
- Homepage: https://github.com/node-modules/formstream#readme
- Issues: https://github.com/node-modules/formstream/issues
- npm.io page: https://npm.io/package/formstream

## Dependencies (4)

- [mime](https://npm.io/package/mime.md) ^2.5.2
- [destroy](https://npm.io/package/destroy.md) ^1.0.4
- [node-hex](https://npm.io/package/node-hex.md) ^1.0.1
- [pause-stream](https://npm.io/package/pause-stream.md) ~0.0.11

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.5.2 (latest) — 2025-07-29
- 1.5.1 — 2024-06-07
- 1.5.0 — 2024-06-06
- 1.4.0 — 2024-05-14
- 1.3.1 — 2023-07-28
- 1.3.0 — 2023-07-27
- 1.2.0 — 2023-03-17
- 1.1.1 — 2021-05-06
- 1.1.0 — 2016-12-19
- 1.0.0 — 2014-11-04
- 0.0.8 — 2014-01-17
- 0.0.7 — 2013-07-25
- 0.0.6 — 2013-07-15
- 0.0.5 — 2012-11-06
- 0.0.4 — 2012-11-06
- … 3 more at https://npm.io/package/formstream/versions

## README

# formstream

[![NPM version][npm-image]][npm-url]
[![CI](https://github.com/node-modules/formstream/actions/workflows/ci.yml/badge.svg)](https://github.com/node-modules/formstream/actions/workflows/ci.yml)
[![Test coverage][codecov-image]][codecov-url]
[![npm download][download-image]][download-url]

[npm-image]: https://img.shields.io/npm/v/formstream.svg?style=flat-square
[npm-url]: https://npmjs.org/package/formstream
[codecov-image]: https://codecov.io/github/node-modules/formstream/coverage.svg?branch=master
[codecov-url]: https://codecov.io/github/node-modules/formstream?branch=master
[download-image]: https://img.shields.io/npm/dm/formstream.svg?style=flat-square
[download-url]: https://npmjs.org/package/formstream

A [multipart/form-data](http://tools.ietf.org/html/rfc2388) encoded stream, helper for file upload.

## Install

```bash
npm install formstream
```

## Quick Start

```js
var formstream = require('formstream');
var http = require('http');

var form = formstream();

// form.file('file', filepath, filename);
form.file('file', './logo.png', 'upload-logo.png');

// other form fields
form.field('foo', 'fengmk2').field('love', 'aerdeng');

// even send file content buffer directly
// form.buffer(name, buffer, filename, mimeType)
form.buffer('file2', new Buffer('This is file2 content.'), 'foo.txt');

var options = {
  method: 'POST',
  host: 'upload.cnodejs.net',
  path: '/store',
  headers: form.headers()
};
var req = http.request(options, function (res) {
  console.log('Status: %s', res.statusCode);
  res.on('data', function (data) {
    console.log(data.toString());
  });
});

form.pipe(req);
```

### Chaining

```js
var fs = require('fs');
var formstream = require('formstream');

var filepath = './logo.png';
fs.stat(filepath, function (err, stat) {
  formstream()
    .field('status', 'share picture')
    .field('access_token', 'your access token')
    .file('pic', filepath, 'logo.png', stat.size)
    .pipe(process.stdout); // your request stream
});
```

### Set min chunk buffer size

Some web servers have a limit on the number of chunks, and you can set `minChunkSize` to ensure the size of chunk sent to the server.

```js
var fs = require('fs');
var FormStream = require('formstream');

var filepath = './big-file.zip';
fs.stat(filepath, function (err, stat) {
  new FormStream({
    // send >= 2MB chunk buffer size to the server
    minChunkSize: 1024 * 1024 * 2,
  }).field('status', 'share file')
    .field('access_token', 'your access token')
    .file('file', filepath, 'big-file.zip', stat.size)
    .pipe(process.stdout); // your request stream
});
```

## API Doc

### formstream([options])

Create a form instance.

#### Arguments

- **options.minChunkSize** Number - min chunk size to emit data event

#### Returns

Form - form instance

### FormStream#field(name, value)

Add a normal field to the form.

#### Arguments

- **name** String - Name of field
- **value** String - Value of field

#### Returns

Form - form instance

### FormStream#file(name, filepath[, filename][, filesize])

Add a local file to be uploaded to the form.

#### Arguments

- **name** String - Name of file field
- **filepath** String - Local path of the file to be uploaded
- ***filename*** String - Optional. Name of the file (will be the base name of `filepath` if empty)
- ***filesize*** Number - Optional. Size of the file (will not generate `Content-Length` header if not specified)

#### Returns

Form - form instance

### FormStream#buffer(name, buffer, filename[, contentType])

Add a buffer as a file to upload.

#### Arguments

- **name** String - Name of field
- **buffer** Buffer - The buffer to be uploaded
- **filename** String - The file name that tells the remote server
- ***contentType*** String - Optional. Content-Type (aka. MIME Type) of content (will be infered with `filename` if empty)

#### Returns

Form - form instance

### FormStream#stream(name, stream, filename[, contentType][, size])

Add a readable stream as a file to upload. Event 'error' will be emitted if an error occured.

#### Arguments

- **name** String - Name of field
- **stream** [stream.Readable](http://nodejs.org/api/stream.html#stream_class_stream_readable) - A readable stream to be piped
- **filename** String - The file name that tells the remote server
- ***contentType*** String - Optional. Content-Type (aka. MIME Type) of content (will be infered with `filename` if empty)
- ***size*** Number - Optional. Size of the stream (will not generate `Content-Length` header if not specified)

#### Returns

Form - form instance

### FormStream#headers([headers])

Get headers for the request.

#### Arguments

- **headers** Object - Additional headers

#### Example

```js
var headers = form.headers({
  'Authorization': 'Bearer kei2akc92jmznvnkeh09sknzdk',
  'Accept': 'application/vnd.github.v3.full+json'
});
```

#### Returns

Object - Headers to be sent.

### Event 'error'

Emitted if there was an error receiving data.

### Event 'data'

The 'data' event emits when a Buffer was used.

See [Node.js Documentation](http://nodejs.org/api/stream.html#stream_event_data) for more.

### Event 'end'

Emitted when the stream has received no more 'data' events will happen.

See [Node.js Documentation](http://nodejs.org/api/stream.html#stream_event_end) for more.

## License

[MIT](LICENSE)

## Contributors

[![Contributors](https://contrib.rocks/image?repo=node-modules/formstream)](https://github.com/node-modules/formstream/graphs/contributors)

Made with [contributors-img](https://contrib.rocks).

---
_Source: https://npm.io/package/formstream · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._