API requests
Retrieve JSON from an HTTP API and convert it into a JavaScript value.
Node.js · Function
fetch
Node.js provides a browser-compatible global fetch() for making HTTP requests. It returns a promise for a Response, whose status and body can be inspected asynchronously.
- Since
- v18.0.0
How it works
fetch() is a browser-compatible global that starts an HTTP request and returns a promise for a Response. Await the response, inspect its status, then consume the body with a response method such as json(); request behavior can be customized through the options object.
Syntax
fetch(input[, init])Parameters
| Name | Type | Description |
|---|---|---|
input | string | URL | Request | The resource URL or request input accepted by the Fetch API. |
init | RequestInit | Optional request configuration, including headers, method, body, and a compatible dispatcher. |
Returns
A Promise that fulfills with a Response object.
Key points
- Node.js exposes a browser-compatible implementation as a global API.
- The underlying client is Undici, which supplies the HTTP/1.1 networking implementation.
- The bundled Undici version can be inspected through the Node.js process version information.
- The fetch ecosystem includes the related global constructors
FormData,Headers,Request, andResponse. - Node.js 18 made fetch available without the experimental-fetch command-line switch.
- Node.js 21.0.0 removed fetch's experimental status.
Common mistakes
- Node.js fetch is implemented on top of Undici, so its networking behavior is not provided by a separate browser runtime.
- A custom dispatcher must be supplied through the options object and must be compatible with Undici's Dispatcher class.
- Changing the global dispatcher affects both Undici and Node.js, so treat that configuration as process-wide.
Example: Fetch and parse JSON
const response = await fetch('https://nodejs.org/api/documentation.json');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data.title);Fetches Node.js documentation, rejects non-successful HTTP statuses, parses the JSON body, and prints its title.
When to use it
Server-side HTTP communication
Send HTTP requests from backend services without adding a separate fetch package.
Advanced transport configuration
Configure Undici-based request routing or connection behavior with a custom dispatcher.
Interview questions
QWhat does Node.js fetch() return and how is the body read?
fetch() is a browser-compatible global in Node.js. It returns a promise for a Response, and the response body must be consumed separately, for example with json().
Follow-up: How can request dispatch be customized? Pass a compatible Undici dispatcher in the fetch options, such as { dispatcher: myDispatcher }.
QIs fetch() built into Node.js, and what implementation does it use?
The API is available globally, so code can call fetch(url) without importing a separate Node.js module. It is implemented using Undici, an HTTP/1.1 client built for Node.js.
Follow-up: How can the implementation version be inspected? Read process.versions.undici in the running Node.js process.
QWhen did Node.js fetch() become stable?
The API became available without the --experimental-fetch flag in Node.js 18. It was marked no longer experimental in Node.js 21.0.0.
Follow-up: Which related globals accompany it? Node.js documents FormData, Headers, Request, and Response as globals available for use with fetch.
Related
FormDataHeadersRequestResponseprocess.versions.undici