@zimic/fetch
Next-gen, TypeScript-first fetch-like API client
npm
•
Docs
•
Examples
•
Issues
•
Roadmap
[](https://github.com/zimicjs/zimic/actions/workflows/ci.yaml)
[](https://github.com/zimicjs/zimic/actions)
[](https://github.com/zimicjs/zimic/blob/canary/LICENSE.md)
[](https://github.com/zimicjs/zimic)
[](https://www.npmjs.com/package/@zimic/fetch)
[](https://bundlephobia.com/package/@zimic/fetch)
---
- [Features](#features)
- [Getting started](#getting-started)
- [Installation](#installation)
- [Basic usage](#basic-usage)
- [Documentation](#documentation)
- [Examples](#examples)
- [Changelog](#changelog)
- [Contributing](#contributing)
---
`@zimic/fetch` is a minimal (1 kB minified and gzipped), zero-dependency, and type-safe `fetch`-like API client.
> [!WARNING]
>
> :construction: This library is **experimental**.
## Features
- :sparkles: **Type-safe `fetch`**: Create a type-safe
[`fetch`-like](https://developer.mozilla.org/docs/Web/API/Fetch_API) API client. Use your
[`@zimic/http` schema](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas) and have your requests and
responses fully typed by default.
- :muscle: **Developer experience**: `@zimic/fetch` seeks to be as compatible with the
[native Fetch API](https://developer.mozilla.org/docs/Web/API/Fetch_API) as possible, while providing an ergonomic
interface to improve type safety. Define default options to apply to your requests, such as a base URL, headers,
search parameters, and more. Inspect and modify requests and responses using
[`onRequest`](https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchonrequest) and
[`onResponse`](https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchonresponse) listeners.
## Getting started
Check our [getting started guide](https://github.com/zimicjs/zimic/wiki/getting‐started‐fetch).
### Installation
| Manager | Command |
| :-----: | --------------------------------------------- |
| npm | `npm install @zimic/http @zimic/fetch --save` |
| yarn | `yarn add @zimic/http @zimic/fetch` |
| pnpm | `pnpm add @zimic/http @zimic/fetch` |
## Basic usage
1. Declare your HTTP schema using [`@zimic/http`](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http):
```ts
import { type HttpSchema } from '@zimic/http';
interface User {
username: string;
}
interface RequestError {
code: string;
message: string;
}
type Schema = HttpSchema<{
'/users': {
POST: {
request: { body: User };
response: {
201: { body: User };
400: { body: RequestError };
409: { body: RequestError };
500: { body: RequestError };
};
};
GET: {
request: {
searchParams: {
query?: string;
limit?: `${number}`;
};
};
response: {
200: { body: User[] };
404: { body: RequestError };
500: { body: RequestError };
};
};
};
'/users/:userId': {
PATCH: {
request: {
headers: { authorization: string };
body: Partial;
};
response: {
204: {};
400: { body: RequestError };
500: { body: RequestError };
};
};
};
}>;
```
2. Create your [fetch client](https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#createfetch):
```ts
import { createFetch } from '@zimic/fetch';
const fetch = createFetch({
baseURL: 'http://localhost:3000',
});
```
3. Enjoy requests and responses typed by default!
```ts
const response = await fetch('/users', {
method: 'GET',
searchParams: { query: 'u', limit: '10' },
});
if (response.status === 404) {
return null; // Not found
}
if (!response.ok) {
throw response.error;
}
const users = await response.json();
return users; // User[]
```
## Documentation
- [Introduction](https://github.com/zimicjs/zimic/wiki)
- [Getting started](https://github.com/zimicjs/zimic/wiki/getting‐started‐fetch)
- [API reference](https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch)
## Examples
Visit our [examples](../../examples/README.md) to see how to use Zimic with popular frameworks, libraries, and use
cases.
## Changelog
The changelog is available on our [GitHub Releases](https://github.com/zimicjs/zimic/releases) page.
## Contributing
Interested in contributing to Zimic? Check out our [contributing guide](../../CONTRIBUTING.md) to get started!