{"id":10881,"library":"fetch-blob","title":"Node.js Blob & File Implementation","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/node-fetch/fetch-blob","tags":["javascript","blob","file","node-fetch","typescript"],"install":[{"cmd":"npm install fetch-blob","lang":"bash","label":"npm"},{"cmd":"yarn add fetch-blob","lang":"bash","label":"yarn"},{"cmd":"pnpm add fetch-blob","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package switched to ESM only since v3. For CJS, use dynamic import: `const { Blob } = await import('fetch-blob')`.","wrong":"const { Blob } = require('fetch-blob')","symbol":"Blob","correct":"import { Blob } from 'fetch-blob'"},{"note":"The File class is exported from a separate `file.js` submodule. Ensure the `.js` extension is included for ESM.","wrong":"import { File } from 'fetch-blob'","symbol":"File","correct":"import { File } from 'fetch-blob/file.js'"},{"note":"Utilities for creating file system-backed Blobs/Files are in `from.js`. Remember the `.js` extension for ESM imports.","wrong":"import { fileFromSync } from 'fetch-blob'","symbol":"fileFromSync","correct":"import { fileFromSync } from 'fetch-blob/from.js'"},{"note":"Requires Node.js v14.6+ for `FinalizationRegistry`. These temporary files are automatically deleted on GC or process exit.","symbol":"createTemporaryFile","correct":"import { createTemporaryFile } from 'fetch-blob/from.js'"}],"quickstart":{"code":"import { Blob } from 'fetch-blob';\nimport { File } from 'fetch-blob/file.js';\nimport { blobFromSync, fileFromSync } from 'fetch-blob/from.js';\nimport { Readable } from 'stream';\nimport { writeFileSync, existsSync, unlinkSync } from 'fs';\nimport { join } from 'path';\n\nconst testFilePath = join(process.cwd(), 'temp-test-file.txt');\nwriteFileSync(testFilePath, 'This is a test file content.');\n\nasync function runQuickstart() {\n  // Create a basic Blob from a string\n  const textBlob = new Blob(['hello, world', ' and some more text'], { type: 'text/plain' });\n  console.log(`Text Blob size: ${textBlob.size} bytes`);\n  console.log(`Text Blob content: ${await textBlob.text()}`);\n\n  // Create a File from an existing file path, without reading into memory\n  const fsFile = fileFromSync(testFilePath, 'text/plain');\n  console.log(`FS File name: ${fsFile.name}`);\n  console.log(`FS File size: ${fsFile.size} bytes`);\n  console.log(`FS File last modified: ${new Date(fsFile.lastModified).toISOString()}`);\n\n  // Combine multiple Blob/File parts into a new Blob\n  const combinedBlob = new Blob([textBlob, fsFile, new Uint8Array([1, 2, 3])]);\n  console.log(`Combined Blob size: ${combinedBlob.size} bytes`);\n\n  // Read the combined blob's stream as a Node.js Readable\n  const nodeStream = Readable.from(combinedBlob.stream());\n  let streamContent = '';\n  for await (const chunk of nodeStream) {\n    streamContent += chunk.toString();\n  }\n  console.log(`Combined Blob stream content (partial): ${streamContent.substring(0, 50)}...`);\n\n  // Clean up the temporary file\n  if (existsSync(testFilePath)) {\n    unlinkSync(testFilePath);\n  }\n}\n\nrunQuickstart().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"`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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Since 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Node.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.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure you import these specific modules using their full path, including the `.js` extension (e.g., `import { File } from 'fetch-blob/file.js'`).","message":"The `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`.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If in a CommonJS module, use `const { Blob } = await import('fetch-blob');` or migrate your module to ESM.","cause":"Attempting to use `new Blob()` in a CommonJS module after v3.0.0 without proper dynamic import.","error":"TypeError: Blob is not a constructor"},{"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.","cause":"Incorrect import path for `File` or file system utilities in an ESM context, possibly missing the `.js` extension or pointing to the wrong entry.","error":"ERR_MODULE_NOT_FOUND: Cannot find package 'fetch-blob/file.js' (or similar with 'from.js')"},{"fix":"Convert the WHATWG stream to a Node.js `Readable` stream first using `Readable.from(blob.stream())`.","cause":"Trying to pipe the WHATWG `ReadableStream` returned by `blob.stream()` directly as if it were a Node.js `Readable` stream.","error":"TypeError: blob.stream(...).pipe is not a function"}],"ecosystem":"npm"}