ofetch
A better fetch API. Works on node, browser, and workers.
Spoiler
🚀 Quick Start
Install:
# npm
npm i ofetch
# yarn
yarn add ofetchImport:
// ESM / Typescript
import { ofetch } from "ofetch";
// CommonJS
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.
keepAlive support
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.
✔️ 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.
// Use JSON.parse
await ofetch("/movie?lang=en", { parseResponse: JSON.parse });
// Return text as is
await ofetch("/movie?lang=en", { parseResponse: (txt) => txt });
// Get the blob version of the response
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");
// FetchError: [GET] "https://google/404": 404 Not Found
// at async main (/project/playground.ts:4:3)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 Early429- 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, // ms
});✔️ 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, // Timeout after 3 seconds
});✔️ Type Friendly
The response can be type assisted:
const article = await ofetch<Article>(`/api/article/${id}`);
// Auto complete working with 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 }) {
// Log request
console.log("[fetch request]", request, options);
// Add `?t=1640125211170` to query search params
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 }) {
// Log 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 }) {
// Log response
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 }) {
// Log error
console.log(
"[fetch response error]",
request,
response.status,
response.body
);
},
});✔️ 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"); // Same as ofetch('/test', { baseURL: '/api' })💡 Adding headers
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",
},
});💡 Adding a HTTP(S) / Proxy Agent
If you need use a HTTP(S) / Proxy Agent, you can (for Node.js only):
Node >= v18
Add ProxyAgent to dispatcher option with undici
import { ofetch } from 'ofetch'
import { ProxyAgent } from 'undici'
await ofetch("/api", {
dispatcher: new ProxyAgent("http://example.com"),
});Node < v18
Add HttpsProxyAgent to agent option with https-proxy-agent
import { HttpsProxyAgent } from "https-proxy-agent";
await ofetch("/api", {
agent: new HttpsProxyAgent("http://example.com"),
});🍣 Access to Raw Response
If you need to access raw response (for headers, etc), can use ofetch.raw:
const response = await ofetch.raw("/sushi");
// response._data
// response.headers
// ...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());📦 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, andufopackages with Babel for ES5 support
- You probably need to transpile
- You need to polyfill
fetchglobal 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 💖