# extension-port-stream

> A module for creating a node style stream over a WebExtension port object.

Latest version **5.0.3** (published 2026-02-13) · ISC license · 0 weekly downloads

## Install

```sh
npm install extension-port-stream
pnpm add extension-port-stream
yarn add extension-port-stream
bun add extension-port-stream
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 5.0.3 |
| Published | 2026-02-13 |
| First published | 2018-08-09 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=22.15.0 |
| Dependencies | 1 |
| Unpacked size | 48.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 24 |
| Author | Dan Finlay |
| Maintainers | danfinlay, kumavis, metamaskbot, gudahtt |
| Keywords | WebExtension, Stream |

## Links

- npm: https://www.npmjs.com/package/extension-port-stream
- Repository: https://git@github.com/MetaMask/extension-port-stream
- Homepage: https://github.com/MetaMask/extension-port-stream#readme
- Issues: https://github.com/MetaMask/extension-port-stream/issues
- npm.io page: https://npm.io/package/extension-port-stream

## Dependencies (1)

- [readable-stream](https://npm.io/package/readable-stream.md) ^3.6.2 || ^4.4.2

## Alternatives

- [byte-size](https://npm.io/package/byte-size.md) — 2.1M weekly downloads
- [speed-limiter](https://npm.io/package/speed-limiter.md) — 16.0K weekly downloads
- [@powersync/node](https://npm.io/package/@powersync/node.md) — 10.9K weekly downloads
- [@ledgerhq/coin-cardano](https://npm.io/package/@ledgerhq/coin-cardano.md) — 1.0K weekly downloads
- [@jayesol/jayeson.lib.streamfinder](https://npm.io/package/@jayesol/jayeson.lib.streamfinder.md) — 1.0K weekly downloads

## Recent versions

- 5.0.3 (latest) — 2026-02-13
- 5.0.2 — 2025-12-18
- 5.0.1 — 2025-12-04
- 5.0.0 — 2025-10-02
- 4.2.0 — 2024-07-01
- 4.1.0 — 2024-06-18
- 4.0.0 — 2024-06-17
- 3.0.0 — 2023-10-27
- 2.1.1 — 2023-06-19
- 2.0.1 — 2021-04-30
- 2.0.0 — 2020-11-23
- 1.0.0 — 2018-08-09

## README

# Extension Port Stream

A module for creating a Node-style stream over a WebExtension [Runtime.Port](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port) object.

## Breaking changes from v4 to v5

1. Chunking mode is enabled by default (see the [Usage](#usage) section below).
2. Node.js-style `Buffer` messages are no longer supported.

Additionally, the timing of logging, errors, and callbacks may be handled differently.

## Usage

By default, `ExtensionPortStream` will send messages in 64MB chunks on Chromium-based browsers.
When this mode is used the receiving end must also use `ExtensionPortStream` in its default mode.

```javascript
import { ExtensionPortStream } from "extension-port-stream";

extension.runtime.onConnect.addListener(connectRemote);
const portStream = new ExtensionPortStream(remotePort, {
  chunkSize: 0, // disable chunking
});

// Enjoy!
```

To disable chunking set the `chunkSize` option to `0`. This will make the transport
mostly backwards compatible with v4.

```javascript
import { ExtensionPortStream } from "extension-port-stream";

extension.runtime.onConnect.addListener(connectRemote);
const portStream = new ExtensionPortStream(remotePort, {
  chunkSize: 0, // disable chunking
});

// Enjoy!
```

### Events

`ExtensionPortStream` extends Node.js `Duplex` stream, so it inherits all EventEmitter capabilities. Additionally, it emits the following custom events:

#### `message-too-large`

Emitted when a message is too large to send in a single `postMessage` call and needs to be chunked. This event is only emitted when chunking is enabled (default).

```javascript
import {
  ExtensionPortStream,
  MessageTooLargeEventData,
} from "extension-port-stream";

const portStream = new ExtensionPortStream(remotePort);

portStream.on("message-too-large", (data: MessageTooLargeEventData) => {
  console.log(
    `Message too large (${
      JSON.stringify(data.message).length
    } bytes), chunking into ${data.chunkSize}-byte pieces`
  );
  console.log("Original error:", data.originalError.message);
});
```

## Running tests

```bash
yarn test
```

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