Registry / http-networking / fetch-blob

fetch-blob

JSON →
library4.0.0jsnpmunverified

fetch-blob provides a robust implementation of the Web Blob and File APIs for Node.js environments, originally forked from `node-fetch`. It is currently at stable version 4.0.0, with frequent minor and patch releases, and major releases addressing breaking changes related to internal architecture or standard compliance. Key differentiators include its ability to handle Blob parts backed by the file system without loading content into memory, and its support for WHATWG streams, requiring explicit conversion for Node.js stream compatibility. While Node.js 18+ includes a native `Blob` class, `fetch-blob` remains relevant for older Node.js versions or for its advanced file system-backed blob capabilities.

npm install fetch-blob
INSTALL
IMPORT
SIG · FETCH-BLOB
F
fetch-blob
http-networkingjavascriptv4.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Blob
✓ import { Blob } from 'fetch-blob'
✗ const { Blob } = require('fetch-blob')
Package switched to ESM only since v3. For CJS, use dynamic import: `const { Blob } = await import('fetch-blob')`.
File
✓ import { File } from 'fetch-blob/file.js'
✗ import { File } from 'fetch-blob'
The File class is exported from a separate `file.js` submodule. Ensure the `.js` extension is included for ESM.
fileFromSync
✓ import { fileFromSync } from 'fetch-blob/from.js'
✗ import { fileFromSync } from 'fetch-blob'
Utilities for creating file system-backed Blobs/Files are in `from.js`. Remember the `.js` extension for ESM imports.
createTemporaryFile
✓ import { createTemporaryFile } from 'fetch-blob/from.js'
Requires Node.js v14.6+ for `FinalizationRegistry`. These temporary files are automatically deleted on GC or process exit.

Demonstrates creating a Blob from text, a File from a file path using `fileFromSync`, combining them into a new Blob, and reading its content via a Node.js Readable stream.

import { Blob } from 'fetch-blob'; import { File } from 'fetch-blob/file.js'; import { blobFromSync, fileFromSync } from 'fetch-blob/from.js'; import { Readable } from 'stream'; import { writeFileSync, existsSync, unlinkSync } from 'fs'; import { join } from 'path'; const testFilePath = join(process.cwd(), 'temp-test-file.txt'); writeFileSync(testFilePath, 'This is a test file content.'); async function runQuickstart() { // Create a basic Blob from a string const textBlob = new Blob(['hello, world', ' and some more text'], { type: 'text/plain' }); console.log(`Text Blob size: ${textBlob.size} bytes`); console.log(`Text Blob content: ${await textBlob.text()}`); // Create a File from an existing file path, without reading into memory const fsFile = fileFromSync(testFilePath, 'text/plain'); console.log(`FS File name: ${fsFile.name}`); console.log(`FS File size: ${fsFile.size} bytes`); console.log(`FS File last modified: ${new Date(fsFile.lastModified).toISOString()}`); // Combine multiple Blob/File parts into a new Blob const combinedBlob = new Blob([textBlob, fsFile, new Uint8Array([1, 2, 3])]); console.log(`Combined Blob size: ${combinedBlob.size} bytes`); // Read the combined blob's stream as a Node.js Readable const nodeStream = Readable.from(combinedBlob.stream()); let streamContent = ''; for await (const chunk of nodeStream) { streamContent += chunk.toString(); } console.log(`Combined Blob stream content (partial): ${streamContent.substring(0, 50)}...`); // Clean up the temporary file if (existsSync(testFilePath)) { unlinkSync(testFilePath); } } runQuickstart().catch(console.error);
Debug
Known issues
breaking`fetch-blob` v3.0.0 switched entirely to ESM (ECMAScript Modules). CommonJS `require()` is no longer directly supported. This also involved internal changes like using private fields and `TextEncoder`/`Decoder`, requiring Node.js 12+ and 11+ respectively.
fix
Migrate your project to ESM imports (`import ... from 'fetch-blob'`) or use dynamic `import()` for CJS compatibility (`const { Blob } = await import('fetch-blob')`). Ensure your Node.js version meets the minimum requirements.
affects: >=3.0.0
breakingSince v3.0.0, `blob.stream()` now returns a WHATWG-compatible `ReadableStream` (an async iterable) instead of a Node.js `Readable` stream. Direct piping or traditional Node.js stream consumers will break.
fix
If you need a Node.js `Readable` stream, convert the WHATWG stream using `Readable.from(blob.stream())` from Node's built-in `stream` module.
affects: >=3.0.0
breakingVersion 4.0.0 removed the dependency on `streams` polyfill. While this reduces bundle size and external dependencies, ensure your environment correctly handles WHATWG streams or use the `Readable.from()` conversion for Node.js streams.
fix
No direct fix for existing code needed unless you were relying on implicit polyfills from `streams`. Continue to use `Readable.from()` for Node.js stream compatibility.
affects: >=4.0.0
gotchaNode.js 18 and later includes a native `Blob` implementation. While `fetch-blob` is still functional, for newer Node.js versions, the native `Blob` might offer better performance or integration. However, `fetch-blob` offers advanced features like file system-backed blobs not present in the native implementation.
fix
Consider if the native `Blob` (`new global.Blob(...)`) meets your needs for basic `Blob` functionality. For file system-backed operations or compatibility with older Node.js, `fetch-blob` remains the go-to.
affects: all
gotchaThe `File` class is exported from `fetch-blob/file.js`, not directly from the main package. Similarly, file system utility functions like `blobFrom`, `fileFrom`, `createTemporaryBlob`, etc., are exported from `fetch-blob/from.js`.
fix
Ensure you import these specific modules using their full path, including the `.js` extension (e.g., `import { File } from 'fetch-blob/file.js'`).
affects: all
Errors
Common errors & fixes
TypeError: Blob is not a constructor
Attempting to use `new Blob()` in a CommonJS module after v3.0.0 without proper dynamic import.
fix
If in a CommonJS module, use `const { Blob } = await import('fetch-blob');` or migrate your module to ESM.
ERR_MODULE_NOT_FOUND: Cannot find package 'fetch-blob/file.js' (or similar with 'from.js')
Incorrect import path for `File` or file system utilities in an ESM context, possibly missing the `.js` extension or pointing to the wrong entry.
fix
Verify the import path, ensuring it's `fetch-blob/file.js` for `File` or `fetch-blob/from.js` for `blobFrom` and related functions. Remember the explicit `.js` extension is crucial for ESM.
TypeError: blob.stream(...).pipe is not a function
Trying to pipe the WHATWG `ReadableStream` returned by `blob.stream()` directly as if it were a Node.js `Readable` stream.
fix
Convert the WHATWG stream to a Node.js `Readable` stream first using `Readable.from(blob.stream())`.
Upgrade
Version history
4.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
fetch-blob — npm install fetch-blob · libregistry