ofetch
A better fetch API. Works on node, browser, and workers.
Spoiler
🚀 Quick Start
Install:
npm i ofetch
yarn add ofetch
Import:
import { ofetch } from "ofetch";
const { ofetch } = require("ofetch");
✔️ Works with Node.js
We use conditional exports to detect Node.js
and automatically use unjs/node-fetch-native. If globalThis.fetch
is available, will be used instead. To leverage Node.js 17.5.0 experimental native fetch API use --experimental-fetch
flag.
✔️ Parsing Response
ofetch
will smartly parse JSON and native values using destr, falling back to the text if it fails to parse.
const { users } = await ofetch("/api/users");
For binary content types, ofetch
will instead return a Blob
object.
You can optionally provide a different parser than destr
, or specify blob
, arrayBuffer
, or text
to force parsing the body with the respective FetchResponse
method.
await ofetch("/movie?lang=en", { parseResponse: JSON.parse });
await ofetch("/movie?lang=en", { parseResponse: (txt) => txt });
await ofetch("/api/generate-image", { responseType: "blob" });
✔️ JSON Body
If an object or a class with a .toJSON()
method is passed to the body
option, ofetch
automatically stringifies it.
ofetch
utilizes JSON.stringify()
to convert the passed object. Classes without a .toJSON()
method have to be converted into a string value in advance before being passed to the body
option.
For PUT
, PATCH
, and POST
request methods, when a string or object body is set, ofetch
adds the default content-type: "application/json"
and accept: "application/json"
headers (which you can always override).
Additionally, ofetch
supports binary responses with Buffer
, ReadableStream
, Stream
, and compatible body types. ofetch will automatically set the duplex: "half"
option for streaming support!
Example:
const { users } = await ofetch("/api/users", {
method: "POST",
body: { some: "json" },
});
✔️ Handling Errors
ofetch
Automatically throws errors when response.ok
is false
with a friendly error message and compact stack (hiding internals).
A parsed error body is available with error.data
. You may also use FetchError
type.
await ofetch("https://google.com/404");
To catch error response:
await ofetch("/url").catch((error) => error.data);
To bypass status error catching you can set ignoreResponseError
option:
await ofetch("/url", { ignoreResponseError: true });
✔️ Auto Retry
ofetch
Automatically retries the request if an error happens and if the response status code is included in retryStatusCodes
list:
Retry status codes:
408
- Request Timeout409
- Conflict425
- Too Early (Experimental)429
- Too Many Requests500
- Internal Server Error502
- Bad Gateway503
- Service Unavailable504
- Gateway Timeout
You can specify the amount of retry and delay between them using retry
and retryDelay
options and also pass a custom array of codes using retryStatusCodes
option.
The default for retry
is 1
retry, except for POST
, PUT
, PATCH
, and DELETE
methods where ofetch
does not retry by default to avoid introducing side effects. If you set a custom value for retry
it will always retry for all requests.
The default for retryDelay
is 0
ms.
await ofetch("http://google.com/404", {
retry: 3,
retryDelay: 500,
});
✔️ Timeout
You can specify timeout
in milliseconds to automatically abort a request after a timeout (default is disabled).
await ofetch("http://google.com/404", {
timeout: 3000,
});
✔️ Type Friendly
The response can be type assisted:
const article = await ofetch<Article>(`/api/article/${id}`);
✔️ Adding baseURL
By using baseURL
option, ofetch
prepends it for trailing/leading slashes and query search params for baseURL using ufo:
await ofetch("/config", { baseURL });
✔️ Adding Query Search Params
By using query
option (or params
as alias), ofetch
adds query search params to the URL by preserving the query in the request itself using ufo:
await ofetch("/movie?lang=en", { query: { id: 123 } });
✔️ Interceptors
Providing async interceptors to hook into lifecycle events of ofetch
call is possible.
You might want to use ofetch.create
to set shared interceptors.
onRequest({ request, options })
onRequest
is called as soon as ofetch
is called, allowing you to modify options or do simple logging.
await ofetch("/api", {
async onRequest({ request, options }) {
console.log("[fetch request]", request, options);
options.query = options.query || {};
options.query.t = new Date();
},
});
onRequestError({ request, options, error })
onRequestError
will be called when the fetch request fails.
await ofetch("/api", {
async onRequestError({ request, options, error }) {
console.log("[fetch request error]", request, error);
},
});
onResponse({ request, options, response })
onResponse
will be called after fetch
call and parsing body.
await ofetch("/api", {
async onResponse({ request, response, options }) {
console.log("[fetch response]", request, response.status, response.body);
},
});
onResponseError({ request, options, response })
onResponseError
is the same as onResponse
but will be called when fetch happens but response.ok
is not true
.
await ofetch("/api", {
async onResponseError({ request, response, options }) {
console.log(
"[fetch response error]",
request,
response.status,
response.body
);
},
});
Passing array of interceptors
If necessary, it's also possible to pass an array of function that will be called sequentially.
await ofetch("/api", {
onRequest: [
() => {
},
() => {
},
],
});
✔️ Create fetch with default options
This utility is useful if you need to use common options across several fetch calls.
Note: Defaults will be cloned at one level and inherited. Be careful about nested options like headers
.
const apiFetch = ofetch.create({ baseURL: "/api" });
apiFetch("/test");
By using headers
option, ofetch
adds extra headers in addition to the request default headers:
await ofetch("/movies", {
headers: {
Accept: "application/json",
"Cache-Control": "no-cache",
},
});
🍣 Access to Raw Response
If you need to access raw response (for headers, etc), can use ofetch.raw
:
const response = await ofetch.raw("/sushi");
🌿 Using Native Fetch
As a shortcut, you can use ofetch.native
that provides native fetch
API
const json = await ofetch.native("/sushi").then((r) => r.json());
🕵️ Adding HTTP(S) Agent
In Node.js (>= 18) environments, you can provide a custom dispatcher to intercept requests and support features such as Proxy and self-signed certificates. This feature is enabled by undici built-in Node.js. read more about the Dispatcher API.
Some available agents:
ProxyAgent
: A Proxy Agent class that implements the Agent API. It allows the connection through a proxy in a simple way. (docs)MockAgent
: A mocked Agent class that implements the Agent API. It allows one to intercept HTTP requests made through undici and return mocked responses instead. (docs)Agent
: Agent allows dispatching requests against multiple different origins. (docs)
Example: Set a proxy agent for one request:
import { ProxyAgent } from "undici";
import { ofetch } from "ofetch";
const proxyAgent = new ProxyAgent("http://localhost:3128");
const data = await ofetch("https://icanhazip.com", { dispatcher: proxyAgent });
Example: Create a custom fetch instance that has proxy enabled:
import { ProxyAgent, setGlobalDispatcher } from "undici";
import { ofetch } from "ofetch";
const proxyAgent = new ProxyAgent("http://localhost:3128");
const fetchWithProxy = ofetch.create({ dispatcher: proxyAgent });
const data = await fetchWithProxy("https://icanhazip.com");
Example: Set a proxy agent for all requests:
import { ProxyAgent, setGlobalDispatcher } from "undici";
import { ofetch } from "ofetch";
const proxyAgent = new ProxyAgent("http://localhost:3128");
setGlobalDispatcher(proxyAgent);
const data = await ofetch("https://icanhazip.com");
Example: Allow self-signed certificates (USE AT YOUR OWN RISK!)
import { Agent } from "undici";
import { ofetch } from "ofetch";
const unsecureAgent = new Agent({ connect: { rejectUnauthorized: false } });
const unsecureFetch = ofetch.create({ dispatcher: unsecureAgent });
const data = await unsecureFetch("https://www.squid-cache.org/");
On older Node.js version (<18), you might also use use agent
:
import { HttpsProxyAgent } from "https-proxy-agent";
await ofetch("/api", {
agent: new HttpsProxyAgent("http://example.com"),
});
keepAlive
support (only works for Node < 18)
By setting the FETCH_KEEP_ALIVE
environment variable to true
, an HTTP/HTTPS agent will be registered that keeps sockets around even when there are no outstanding requests, so they can be used for future requests without having to re-establish a TCP connection.
Note: This option can potentially introduce memory leaks. Please check node-fetch/node-fetch#1325.
📦 Bundler Notes
- All targets are exported with Module and CommonJS format and named exports
- No export is transpiled for the sake of modern syntax
- You probably need to transpile
ofetch
, destr
, and ufo
packages with Babel for ES5 support
- You need to polyfill
fetch
global for supporting legacy browsers like using unfetch
❓ FAQ
Why export is called ofetch
instead of fetch
?
Using the same name of fetch
can be confusing since API is different but still, it is a fetch so using the closest possible alternative. You can, however, import { fetch }
from ofetch
which is auto-polyfill for Node.js and using native otherwise.
Why not have default export?
Default exports are always risky to be mixed with CommonJS exports.
This also guarantees we can introduce more utils without breaking the package and also encourage using ofetch
name.
Why not transpiled?
By transpiling libraries, we push the web backward with legacy code which is unneeded for most of the users.
If you need to support legacy users, you can optionally transpile the library in your build pipeline.
License
MIT. Made with 💖