Synchronous Fetch API for Node.js and Browser

Common errors

• Cannot use Stream or Blob as request body

  cause The synchronous nature of `sync-fetch` in Node.js prevents it from reading or serializing asynchronous data types like `Stream` or `Blob` for the request body.
  fix Convert `Stream` or `Blob` data into a synchronously readable format (e.g., `Buffer` or string) before passing it as the `body` option.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported

  cause This error occurs when attempting to `require()` an ECMAScript Module (ESM) in a CommonJS context. While `sync-fetch` provides a CommonJS `require` entry, its internal dependency `node-fetch` v3 is ESM-only. This error might indicate an incompatibility or misconfiguration if `sync-fetch`'s internal mechanisms fail to bridge the CJS/ESM gap correctly for its dependencies, or if you are trying to `import` `sync-fetch` directly in an ESM project where it only exposes CJS.
  fix For Node.js, ensure you are using `const fetch = require('sync-fetch')`. If the error persists due to internal dependencies, verify your Node.js runtime environment (>=18 is required). If you are in an ESM project, and `sync-fetch` does not provide an ESM export, you might need to use dynamic `import()` or tools that bridge CJS and ESM, though this package's core design revolves around synchronous CJS for Node.js.

• Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects to the end user's experience.

  cause This is a browser console warning (or error in strict environments) indicating that you are using `sync-fetch` on the browser's main UI thread, which causes the page to become unresponsive during the network request.
  fix Refactor your code to use the standard, asynchronous `fetch` API for browser main thread operations. If synchronous behavior is absolutely required, move the `sync-fetch` call into a Web Worker to avoid blocking the UI thread.

Warnings

• breaking This package provides synchronous I/O. Using `sync-fetch` on the main thread of a browser will block the UI, making the page unresponsive. In Node.js, it will block the event loop, halting all other operations and significantly degrading application performance. It is generally suitable only for Web Workers or CLI tools where blocking is acceptable or desired.
  Fix: For browser applications, use standard, asynchronous `fetch` or ensure `sync-fetch` is only used within a Web Worker. For Node.js, prefer asynchronous I/O with `node-fetch` or other promise-based libraries unless a blocking operation is strictly required for a specific, isolated use case (e.g., a CLI tool's initial setup).
• gotcha The Node.js implementation of `sync-fetch` has significant limitations on request body types. It does not support `Stream`, `Blob`, or `FormData` instances as input bodies because they cannot be read or serialized synchronously. Additionally, the non-spec `agent` option is not supported.
  Fix: For Node.js, ensure request bodies are JSON, strings, or `Buffer` objects that can be serialized synchronously. Avoid using `Stream`, `Blob`, or `FormData` directly as body content.
• gotcha When used in browser environments, `sync-fetch` relies on `XMLHttpRequest` and consequently supports only a limited set of `fetch` options (`method`, `body`, `headers`, `credentials`, `timeout`). Standard `fetch` features like `redirect`, `integrity`, or `cache` are often unavailable. CORS limitations apply and may be stricter for synchronous requests.
  Fix: Be aware of reduced functionality in browsers. Test thoroughly for desired behavior, especially concerning CORS. For advanced `fetch` options, consider asynchronous `fetch`.
• gotcha While `sync-fetch` relies on `node-fetch` internally, `node-fetch` v3 is an ESM-only module. If you are working in a CommonJS Node.js project and face issues related to `require()` of ESM modules, it might stem from `sync-fetch`'s internal dependency resolution, even though `sync-fetch` itself exposes a CommonJS `require` interface.
  Fix: If encountering `ERR_REQUIRE_ESM` when using `sync-fetch` in a CJS project, verify your Node.js version and environment. Ensure `sync-fetch`'s internal handling of `node-fetch` v3 is compatible, or consider alternative synchronous HTTP clients if issues persist.

Install

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

Imports

• fetch
  wrong:

  import fetch from 'sync-fetch'

  correct:

  const fetch = require('sync-fetch')

  For Node.js, this package primarily offers a CommonJS `require` interface as shown in its documentation. Direct ESM `import` may not work without a bundler or specific Node.js configuration, as `node-fetch` v3 (its dependency) is ESM-only.
• fetch (global)

  <script src="https://unpkg.com/sync-fetch"></script>
  // 'fetch' is now globally available

  In browser environments, `sync-fetch` is typically loaded via a CDN, making the `fetch` function globally accessible. Be aware of CORS and other browser limitations for synchronous XHR.
• SyncResponse methods
  wrong:

  const response = await fetch('http://example.com');
  const data = await response.json();

  correct:

  const response = fetch('http://example.com');
  const data = response.json(); // or .text(), .buffer(), etc.

  All `SyncResponse` methods (e.g., `.json()`, `.text()`, `.buffer()`, `.blob()`, `.arrayBuffer()`) return values synchronously, unlike the asynchronous `Promise`-returning methods of the standard Fetch API.

Quickstart

Demonstrates a basic synchronous GET request and synchronously parses a JSON response, followed by a text response and an example using an environment variable for authentication.

const fetch = require('sync-fetch');

const metadata = fetch('https://doi.org/10.7717/peerj-cs.214', {
  headers: {
    Accept: 'application/vnd.citationstyles.csl+json'
  }
}).json();

console.log('DOI Metadata:', metadata);

// Example of synchronous text response
const textResponse = fetch('https://httpbin.org/get').text();
console.log('Plain Text Response (first 100 chars):', textResponse.substring(0, 100) + '...');

// Example with environment variable for API key (placeholder)
const apiKey = process.env.SOME_API_KEY ?? 'your_default_key';
// In a real scenario, avoid embedding keys directly. This is for demonstration.
const secureResponse = fetch(`https://api.example.com/data?key=${apiKey}`).json();
console.log('Secure Data (first 50 chars):', JSON.stringify(secureResponse).substring(0, 50) + '...');