Node.js Stream API for Browsers (Browserify)

3.0.0 · active · verified Tue Apr 21

stream-browserify is a module that provides the Node.js `stream` API for browser environments. It serves as a polyfill, allowing npm packages designed for Node.js streams to function correctly within a browser context when bundled. The current stable version is 3.0.0, released after a period of using `readable-stream` v2, and now fully leverages `readable-stream` v3. This package is primarily intended for use with bundlers like Browserify, which automatically substitute the native Node.js `stream` module with `stream-browserify` during the bundling process. Its key differentiator is providing a consistent, spec-compliant stream implementation that bridges the gap between Node.js module expectations and browser limitations, ensuring broad compatibility for legacy and modern stream APIs in the browser.

Common errors

```
TypeError: stream.Readable is not a constructor
```
cause This typically occurs in a browser environment where the native Node.js 'stream' module is not available or has not been correctly polyfilled by a bundler, or if an old CJS `require` is used in an incompatible ESM context.

fix Ensure your project is bundled with a tool like Browserify that provides `stream-browserify` as a shim for `require('stream')`. If directly importing, use `import { Readable } from 'stream-browserify';`. Verify bundler configuration.
```
Cannot find module 'stream'
```
cause This error means that `require('stream')` or `import 'stream'` could not be resolved, most commonly in a browser environment without an appropriate polyfill or bundler configuration.

fix If using Browserify, ensure `stream-browserify` is correctly integrated by the bundler. If not using a bundler or needing a global stream polyfill, you might need to manually configure aliasing or ensure `stream-browserify` is included in your build process.

Warnings

breaking Version 3.0.0 upgrades to `readable-stream` v3. This introduces several breaking changes inherited from `readable-stream` itself, aligning with Node.js 10+ stream APIs. Developers should consult the `readable-stream` v3 release notes for detailed information.
Fix: Review the `readable-stream` v3 documentation for breaking changes (e.g., changes to `_read` behavior, error handling, `pipeline`, and `finished` utilities). Adapt stream implementations and consumption patterns accordingly.
gotcha Direct installation of `stream-browserify` is often unnecessary. Bundlers like Browserify automatically include and alias this module when `require('stream')` is encountered in browser environments.
Fix: If using Browserify, avoid explicit `npm install stream-browserify` unless a specific version conflict or direct module access is required. Rely on the bundler's resolution.
gotcha Mixing different versions of `readable-stream` (or `stream-browserify` which depends on it) within a single application can lead to unpredictable behavior and compatibility issues, especially when libraries expect specific stream API behaviors.
Fix: Use `npm ls readable-stream` or `yarn why readable-stream` to inspect your dependency tree. Resolve any duplicate or conflicting `readable-stream` versions to ensure a consistent stream implementation across your project. Consider `resolutions` or `overrides` if necessary.

Install

npm install stream-browserify npm
yarn add stream-browserify yarn
pnpm add stream-browserify pnpm

Imports

Readable
wrong:
```
const Readable = require('stream-browserify').Readable;
```
correct:
```
import { Readable } from 'stream-browserify';
```
While named imports are supported for direct usage, bundlers like Browserify typically remap `require('stream')` to this module.
Writable
wrong:
```
import Writable from 'stream-browserify/writable';
```
correct:
```
import { Writable } from 'stream-browserify';
```
All stream classes are exported as named exports from the main entry point.
Transform
wrong:
```
const stream = require('stream-browserify'); const Transform = stream.Transform;
```
correct:
```
import { Transform } from 'stream-browserify';
```
CommonJS `require('stream-browserify').Transform` is also a valid pattern, especially when using Browserify which shims `require('stream')`.

Quickstart

Demonstrates creating and piping a basic readable stream to a writable stream using `stream-browserify`.

import { Readable, Writable } from 'stream-browserify';

class MyReadable extends Readable {
  constructor(options) {
    super(options);
    this.index = 0;
  }

  _read(size) {
    if (this.index < 5) {
      this.push(`Chunk ${this.index++}\n`);
    } else {
      this.push(null); // No more data
    }
  }
}

class MyWritable extends Writable {
  _write(chunk, encoding, callback) {
    console.log(`Received: ${chunk.toString()}`);
    callback();
  }
}

const readableStream = new MyReadable();
const writableStream = new MyWritable();

readableStream.pipe(writableStream);

// Expected output:
// Received: Chunk 0
// Received: Chunk 1
// Received: Chunk 2
// Received: Chunk 3
// Received: Chunk 4

view raw JSON →