Node.js Blob & File Implementation

Common errors

• TypeError: Blob is not a constructor

  cause 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')

  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.
  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

  cause 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())`.

Warnings

• 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.
• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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`.
  Fix: Ensure you import these specific modules using their full path, including the `.js` extension (e.g., `import { File } from 'fetch-blob/file.js'`).

Install

• npm install fetch-blob npm
• yarn add fetch-blob yarn
• pnpm add fetch-blob pnpm

Imports

• Blob
  wrong:

  const { Blob } = require('fetch-blob')

  correct:

  import { Blob } from 'fetch-blob'

  Package switched to ESM only since v3. For CJS, use dynamic import: `const { Blob } = await import('fetch-blob')`.
• File
  wrong:

  import { File } from 'fetch-blob'

  correct:

  import { File } from 'fetch-blob/file.js'

  The File class is exported from a separate `file.js` submodule. Ensure the `.js` extension is included for ESM.
• fileFromSync
  wrong:

  import { fileFromSync } from 'fetch-blob'

  correct:

  import { fileFromSync } from 'fetch-blob/from.js'

  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.

Quickstart

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);