Skip to main content

Getting started

This guide will help you get started with @zimic/fetch.

Requirements​

Supported environments​

Client side​

@zimic/fetch is designed to work in any environment that supports the Fetch API. This includes any relatively modern browser. Can I Use is a great resource to check the compatibility of specific features with different browsers.

Server side​

RuntimeVersion
Node.js>= 18.0.0

Supported languages​

TypeScript​

@zimic/fetch requires TypeScript >= 5.0.

We recommend enabling strict in your tsconfig.json:

tsconfig.json
{
  "compilerOptions": {
    "strict": true
  }
}

JavaScript​

@zimic/fetch is fully functional on JavaScript, although the type features will be disabled. Consider using TypeScript for improved type safety and developer experience.

Installation​

@zimic/fetch is available as a library on npm.

npm install @zimic/http @zimic/fetch --save
info

Note that @zimic/http is a peer dependency of @zimic/fetch, so you need to install both packages. When upgrading @zimic/fetch to a new version, consider upgrading @zimic/http as well to ensure that the versions are compatible.

We also have canary releases under the tag canary. These have the latest code, including new features, bug fixes, and possibly unstable or breaking changes.

npm install @zimic/http@canary @zimic/fetch@canary --save

Your first fetch instance​

Declaring an HTTP schema​

To start using @zimic/fetch, declare an HTTP schema using @zimic/http:

The schema represents the structure of your API, including the paths, methods, request and response types.

TIP: OpenAPI Typegen

For APIs with an OpenAPI documentation (e.g. Swagger), the zimic-http typegen CLI can automatically infer the types and generate the schema for you. This is a great way to keep your schema is up to date and save time on manual type definitions.

schema.ts
import { 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 };
      };
    };

    GET: {
      request: {
        headers: { authorization: string };
        searchParams: {
          query?: string;
          limit?: number;
        };
      };
      response: {
        200: { body: User[] };
        400: { body: RequestError };
        401: { body: RequestError };
      };
    };
  };

  '/users/:userId': {
    PATCH: {
      request: {
        headers: { authorization: string };
        body: Partial<User>;
      };
      response: {
        204: {};
        400: { body: RequestError };
      };
    };
  };
}>;

Creating a fetch instance​

With the schema defined, you can now create a fetch instance.

@zimic/fetch provides a createFetch function that takes the schema as a type parameter and returns a thin wrapper around the native Fetch API. It adds type safety for making requests and handling responses, all automatically typed based on the schema.

import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

Set the baseURL option to the base URL of your API. It will be prepended to all requests made with this instance.

You can also set other options, such as default headers, credentials, parameters, and more. Refer to the createFetch API reference for more details.

Making requests​

You can now use the fetch instance to make requests to your API. All paths, methods, parameters, requests, and responses are typed by default based on the schema.

const response = await fetch('/users', {
  method: 'GET',
  searchParams: { query: 'u', limit: 10 },
});

// If the user was not found, return null
if (response.status === 404) {
  return null;
}

// If the request status is 4XX or 5XX), throw an error
if (!response.ok) {
  throw response.error;
}

// If the request was ok, the data type is inferred as User[]
const users = await response.json();
return users;

Next steps​

Guides​

Take a look at our guides for more information on how to use @zimic/fetch in common scenarios.

Examples​

Try our examples for more practical use cases of @zimic/fetch with popular libraries and frameworks.

API reference​

Visit the API reference for more details on the resources available in @zimic/fetch.

Explore the ecosystem​

  • Access the @zimic/http documentation to learn more about extending your HTTP schema.

  • If you are interested in mocking your requests in development and testing, check out @zimic/interceptor. Declare realistic HTTP mocks validated with the same schema as your fetch client, and verify that your application interacts as expected, without needing to access the actual API.