Using headers

HTTP headers are key-value pairs that contain additional information about a request or a response. They are commonly used to pass metadata, such as a content type, authentication tokens, or caching directives.

Using request headers

To send headers in your requests, declare their types in your schema.

schema.ts

import { HttpSchema } from '@zimic/http';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      request: {
        headers: {
          authorization: string;
          'accept-language'?: string;
        };
      };
      response: {
        200: { body: User[] };
      };
    };
  };
}>;

Then, set the headers in your fetch request using the headers option. They are typed and validated according to your schema, providing type safety and autocompletion.

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

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

const response = await fetch('/users', {
  method: 'GET',
  headers: {
    authorization: `Bearer ${accessToken}`,
    'accept-language': 'en',
  },
});

Using default request headers

A fetch instance can have defaults that are applied to all requests. These include headers:

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

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

You can also set headers after the fetch instance is created. This is useful for setting headers that are dynamic, such as authentication tokens.

fetch.defaults.headers['accept-language'] = 'en';
fetch.defaults.headers.authorization = `Bearer ${accessToken}`;

fetch.onRequest can also be used to set headers. Use this listener if you need to apply logic to the headers, such as reading them from local storage or limiting them to specific requests.

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

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

  onRequest(request) {
    if (this.isRequest(request, 'GET', '/users')) {
      request.headers.set('accept-language', 'en');
    }
    return request;
  },
});

Using response headers

Similarly to requests, you can declare the types of response headers in your schema.

schema.ts

import { HttpSchema } from '@zimic/http';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: {
        200: {
          headers: {
            'content-type': 'application/json';
            'content-encoding'?: string;
          };
          body: User[];
        };
      };
    };
  };
}>;

When a response is received, the headers are available at response.headers.

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

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

const response = await fetch('/users', {
  method: 'GET',
});

console.log(response.headers.get('content-type')); // application/json
console.log(response.headers.get('content-encoding')); // string | null

Using cookies

Cookies can store data on the client side and are often used for authentication, session management, and tracking user preferences.

Since cookies are a type of header, you can use them in the same way as other headers, declaring them in your schema and accessing them in requests and responses.

schema.ts

import { HttpSchema } from '@zimic/http';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      request: {
        headers: { cookie?: string };
      };
      response: {
        200: {
          headers: { 'set-cookie'?: string };
          body: User[];
        };
      };
    };
  };
}>;

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

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

const response = await fetch('/users', {
  method: 'GET',
  headers: { cookie: 'sessionId=1e9f65ab; theme=dark' },
});

console.log(response.headers.get('set-cookie'));

INFO: Cookies in browsers

Cookies are automatically sent by a browser, so you don't need to manually set them when making requests. For more information about cookies, see the MDN documentation.

WARNING: HttpOnly cookies

Cookies marked with the HttpOnly flag are not accessible via client-side JavaScript. Even though they may be in your schema and included in the requests, you won't be able to access them in your browser code, only on the server.