Frontend HTTP client

Opinionated HTTP client for the frontend.

Note that it is a ESM-only package.

Basic usage

import wretch from 'wretch'
import { z } from 'zod/v4'

const client = wretch('http://localhost:8000')

const queryParamsSchema = z.object({
	param1: z.string(),
	param2: z.number(),
})

const requestBodySchema = z.object({
	requestCode: z.number(),
})

const responseBodySchema = z.object({
	success: z.boolean(),
})

const responseBody = await sendPost(client, {
	path: '/',
	body: { requestCode: 100 },
	queryParams: { param1: 'test', param2: 123 },
	queryParamsSchema,
	requestBodySchema,
	responseBodySchema,
})

No content response handling (HTTP 204)

SDK methods has a parameter (isEmptyResponseExpected) to specify if 204 response should be treated as an error or not. By default it is treated as valid except on sendGet method where it is treated as an error. Usage example:

const response = await sendGet(client, {
	path: '/',
	isEmptyResponseExpected: true,
})

if 204 responses are expected, the library will return null, if not, it will throw an error.

Non-JSON response handling

SDK methods has a parameter (isNonJSONResponseExpected) to specify if non json responses should be treated as an error or not. By default it is treated as valid except on sendGet method where it is treated as an error. Usage example:

const response = await sendGet(client, {
	path: '/',
	isNonJSONResponseExpected: true,
})

if non-JSON responses are expected, the library will return null, if not, it will throw an error.

API contract-based requests

frontend-http-client supports using API contracts, created with @lokalise/api-contracts in order to make fully type-safe HTTP requests.

Usage example:

import { somePostRouteDefinition, someGetRouteDefinition } from 'some-service-api-contracts'
import { sendByPayloadRoute } from '@lokalise/frontend-http-client'
import wretch from 'wretch'

const client = wretch(BASE_URL)

const responseBody1 = await sendByPayloadRoute(client, somePostRouteDefinition, {
    pathParams: {
        userId: 1,
    },
    body: {
        isActive: true,
    },
})

const responseBody2 = await sendByGetRoute(client, someGetRouteDefinition, {
    pathParams: {
        userId: 1,
    },
    queryParams: {
        id: 'testId',
    },
})

The following parameters can be specified when sending API contract-based requests:

• body - request body (only applicable for sendByPayloadRoute, type needs to match with contract definition)
• queryParams - query parameters (type needs to match with contract definition)
• headers - custom headers to be sent with the request (type needs to match with contract definition)
• pathParams – parameters used for path resolver (type needs to match with contract definition)
• pathPrefix - optional prefix to be prepended to the path resolved by the contract's path resolver

Tracking request progress

Tracking requests progress is especially useful while uploading files.

Important note: wretch does not support request progress tracking, so we rely on XMLHttpRequest. That's why the interface of the method below is slightly different from the others

Usage example:

 const response = await sendPostWithProgress({
    path: '/',
    data: new FormData(), 
    headers: { Authorization: 'Bearer ...' }, 
    responseBodySchema: z.object(),
    onProgress: (progress) => {
        console.log(`Loaded ${progress.loaded} of ${progress.total}`)
    }
})

Aborting pending requests

Aborting requests is especially useful while uploading files.

Important note: Currently it is only possible with sendWithProgress() function

Usage example:

const abortController = new AbortController()

sendPostWithProgress({
    path: '/',
    data: new FormData(), 
    headers: { Authorization: 'Bearer ...' },
    responseBodySchema: z.object(),
    onProgress: (progress) => {
        console.log(`Loaded ${progress.loaded} of ${progress.total}`)
    },
    abortController
})

abortController.abort()

Credits

This library is brought to you by a joint effort of Lokalise engineers:

• Ondrej Sevcik
• Szymon Chudy
• Nivedita Bhat
• Arthur Suermondt
• Lauris Mikāls
• Oskar Kupski
• Igor Savin