@whatwg-node/fetch

What is @whatwg-node/fetch?

@whatwg-node/fetch is an npm package that provides a WHATWG Fetch API implementation for Node.js. It allows developers to use the familiar Fetch API, which is standard in web browsers, in a Node.js environment. This package is useful for making HTTP requests, handling responses, and working with various types of data formats.

What are @whatwg-node/fetch's main functionalities?

Basic Fetch Request

This feature allows you to make a basic HTTP GET request to a specified URL and handle the response. The example fetches a post from a placeholder API and logs the JSON response.

const fetch = require('@whatwg-node/fetch');

fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

POST Request with JSON Body

This feature allows you to make an HTTP POST request with a JSON body. The example sends a new post to the placeholder API and logs the JSON response.

const fetch = require('@whatwg-node/fetch');

const data = { title: 'foo', body: 'bar', userId: 1 };

fetch('https://jsonplaceholder.typicode.com/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Handling Different Response Types

This feature demonstrates how to handle different response types and errors. The example checks if the response is OK before parsing it as JSON, and throws an error if the response is not OK.

const fetch = require('@whatwg-node/fetch');

fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    if (response.ok) {
      return response.json();
    } else {
      throw new Error('Network response was not ok');
    }
  })
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Other packages similar to @whatwg-node/fetch

node-fetch

node-fetch is a lightweight module that brings `window.fetch` to Node.js. It is widely used and has a similar API to the Fetch API in browsers. Compared to @whatwg-node/fetch, node-fetch is more mature and has a larger user base.

axios

axios is a promise-based HTTP client for Node.js and the browser. It provides a more feature-rich API compared to the Fetch API, including request and response interceptors, automatic JSON transformation, and more. It is more versatile but also more complex than @whatwg-node/fetch.

got

got is a human-friendly and powerful HTTP request library for Node.js. It supports many advanced features like retries, streams, and hooks. Compared to @whatwg-node/fetch, got offers more advanced features and better error handling.

README

@whatwg-node/fetch

A ponyfill package for the Fetch Standard. If your JavaScript environment doesn't implement this standard natively, this package automatically ponyfills the missing parts, and export them as a module; otherwise it exports the native ones without touching the environment's internals. It also exports some additional standard APIs that are required by the Fetch Standard.

Installation

yarn add @whatwg-node/fetch

Why Fetch API and why this ponyfill in general?

If you are building a JavaScript library, and you want it to support all JavaScript environments not only Node.js. Fetch API is the best choice for you. Because it's a standard, and it's implemented by the most environments out there expect Node.js :). So you can use Fetch API in your library, and your users can use it in their browsers, Deno, Bun, Cloudflare Works, and in Node.js.

This is how we support all JavaScript environments in GraphQL Yoga. In GraphQL Yoga, we don't care which JavaScript environment you prefer, we support all of them.

Why we should still use these for Node.js even if it already implements them natively

Even if newer Node.js already implements Fetch API and Data Text Encoding API natively, we still recommend to use this package, because this package implements them for Node.js in more efficient way.

• See problems with the global fetch/undici in Node.js
• • We offer a patched version of node-fetch that doesn't use undici and Node.js streams internally, so it's more efficient than the native one.
• See problems with text encoding API in Node.js
• • We use Buffer instead of the native one, because Buffer is faster than the native one unfortunately.
• Body.formData() is not implemented by Node.js, so we implement it with busboy internally. So you can consume incoming multipart(file uploads) requests with .formData in Node.js.
• fetch implementation of Node.js uses undici and it doesn't support HTTP 2, our implementation supports it natively thanks to node-libcurl.

Faster HTTP Client in Node.js with HTTP/2 support

If you install node-libcurl seperately, @whatwg-node/fetch will select libcurl instead of node:http which is faster.

See benchmarks

Handling file uploads with Fetch API

import { Request } from '@whatwg-node/fetch'

// See how you can handle file uploads with Fetch API
http.createServer(async (req, res) => {
  const request = new Request(req)
  const formData = await request.formData()
  const file = formData.get('file')
  // ...
})

If you want to limit the size of the multipart form data, you can use createFetch. See the API section for more details.

API

The following are exported by this package:

WHATWG Fetch Standard

• fetch
• Request
• Response
• Headers
• FormData
• AbortController

Web Streams API

• ReadableStream
• WritableStream
• TransformStream

URL Standard

• URL
• URLSearchParams
• URLPattern

Data Types

• Blob
• File

Data Encoding/Decoding API

• TextEncoder
• TextDecoder
• btoa

Web Crypto API

• crypto

Create variations of the implementation

• createFetch

createFetch allows you to create an API with some specific flags that are not available in the actual API.

Limit the multipart form data size

This is useful if you parse the multipart request bodies with .formData().

import { createFetch } from '@whatwg-node/fetch'

const fetchAPI = createFetch({
  formDataLimits: {
    // Maximum allowed file size (in bytes)
    fileSize: 1000000,
    // Maximum allowed number of files
    files: 10,
    // Maximum allowed size of content (operations, variables etc...)
    fieldSize: 1000000,
    // Maximum allowed header size for form data
    headerSize: 1000000
  }
})

// See how you can handle file uploads with Fetch API
http.createServer(async (req, res) => {
  const request = new Request(req)
  const formData = await request.formData()
  const file = formData.get('file')
  // ...
})