The pragmatic native fetch API wrapper for JavaScript.
Just arguments and wraps native fetch so can work in any framework or JavaScript environment where fetch is available with no additional setup needed.
👉 See Full Documentation
- Framework Agnostic – use in any JavaScript project.
- Zero dependencies, just wraps the native fetch API.
- Intuitive modern API with per-request configuration and flexibility.
- Supports request cancellation on demand or on timeout.
- Global configuration for common request options.
- Supports all native fetch API options.
- Built-in caching with auto revalidation.
- Built-in request retries and configurable polling.
- Built-in helpers for common use cases such as setting bearer token!
- Auto JSON parsing and graceful error handling.
- Builtin hooks or interceptors.
- Request refetching on demand.
- New! Additional HTTP methods: OPTIONS, TRACE, HEAD and a CUSTOM method for any other HTTP verb.
- New! TypeScript support for better type safety and autocompletion.
- New! Test coverage for all core features and methods, for better reliability.
-
Using npm, yarn or pnpm
npm install @z-fetch/fetch
Z-Fetch allows you to create custom instances with their own configuration, which is useful for different API endpoints or services in your application.
import { createInstance } from "@z-fetch/fetch";
// Create a custom instance with specific configuration
const api = createInstance({
baseUrl: "https://jsonplaceholder.typicode.com",
headers: {
"X-Custom-Header": "custom-value",
},
timeout: 30000,
});
// Use the instance to make requests
const getPosts = async () => {
const result = await api.get("/posts");
if (result?.data) {
console.log("Posts:", result.data);
}
};
const createPost = async () => {
const result = await api.post("/posts", {
body: {
title: "New Post",
body: "This is the content",
userId: 1,
},
});
if (result?.data) {
console.log("Created post:", result.data);
}
};import { GET } from "@z-fetch/fetch";
const getPosts = async () => {
const { data, error } = await GET(
"https://jsonplaceholder.typicode.com/posts",
);
if (data) {
console.log("Data:", data);
} else {
console.error("Error:", error.message);
}
};import { POST } from "@z-fetch/fetch";
const createPost = async () => {
const { data, error } = await POST(
"https://jsonplaceholder.typicode.com/posts",
{
body: {
title: "dune",
body: "a story about the dune verse!",
userId: 1,
},
},
);
if (data) {
console.log("Data:", data);
} else {
console.error("Error:", error.message);
}
};👉 Visit the docs for more examples on how to use and to explore full functionality.
- Cancel early via the returned promise:
const p = GET('/users'); p.cancel(); const r = await p; error.statusis"CANCELED"with message"Request canceled".- Timeouts set
error.statusto"TIMEOUT"with message"Request timed out!". - Instances also expose
result.cancelRequest()on the resolved result for aborting ongoing work.
// Cancel a request
const p = api.get("/users", { timeout: 10000 });
setTimeout(() => p.cancel(), 50);
const res = await p;
if (res.error?.status === "CANCELED") {
// handle cancel
}- Successful GETs are cached when
withCache: true. - Failed or canceled GETs are NOT cached; subsequent calls hit the network.
- Background revalidation runs after
revalidateCachems; on failure, cached data is preserved.
const api = createInstance({ withCache: true, revalidateCache: 1000 });
await api.get("/items"); // caches on success
const { data } = await api.get("/items"); // served from cache; revalidates in backgroundwithCredentials: truesets fetchcredentials: 'include'and XHRwithCredentials = true.- By default credentials are not included. You can still set native
credentialsper request whenwithCredentialsis not used.
Now you can pass bearerToken directly in request options:
import { GET, POST } from "@z-fetch/fetch";
// Pass bearer token in request options
const result = await GET("/api/protected", {
bearerToken: "your-token-here",
});
// Works with all HTTP methods
const postResult = await POST("/api/data", {
body: { title: "My Post" },
bearerToken: "your-token-here",
});Instance options like withCredentials now work correctly:
import { createInstance } from "@z-fetch/fetch";
const api = createInstance({
baseUrl: "https://api.example.com",
withCredentials: true, // Now works properly!
headers: {
"Content-Type": "application/json",
},
});
// All requests will include credentials
const result = await api.get("/user-data");Z-Fetch provides a consistent { data, error } result for all requests. HTTP errors (4xx, 5xx), network errors, timeouts, and cancellations all populate the error object with a unified structure.
import { createInstance, GET } from "@z-fetch/fetch";
const api = createInstance({
baseUrl: "https://api.example.com",
});
// Always destructure data and error
const { data, error } = await api.get("/protected");
if (error) {
// Unified error structure for all error types
console.log("Error:", error.message); // Error message
console.log("Status:", error.status); // 401, 404, 500, "NETWORK_ERROR", "TIMEOUT", etc.
console.log("Data:", data); // Response body still parsed even on error
} else {
console.log("Success:", data);
}Customize error messages by status code or pattern using errorMapping:
const api = createInstance({
baseUrl: "https://api.example.com",
errorMapping: {
// Map status codes to custom messages
401: "Authentication failed - please sign in again",
403: "Access denied - insufficient permissions",
404: "Resource not found",
500: "Server error - please try again later",
// Map z-fetch internal errors
NETWORK_ERROR: "Network connection failed",
TIMEOUT: "Request took too long",
},
});
const { data, error } = await api.get("/protected");
if (error) {
console.log(error.message); // Uses custom mapped message
console.log(error.status); // 401, 404, 500, etc.
}Note: Error mapping is optional. When no mapping is provided for a status code, the library uses response.statusText as the default message.
mapErrors and throwOnError configuration options have been removed. Z-Fetch now always creates error objects for HTTP errors and never throws. The API is unified - always use const { data, error } = result for all requests.
That’s it for now! More features will surely come, but this version of Z-Fetch already elevates fetching in your applications with enhanced flexibility and control. Feel free to contribute, share suggestions, or propose new features. I’d be happy to hear from you!
Humble regards, I am Hussein Kizz