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.

The unified sendByContract method accepts any route definition (GET, POST, PUT, PATCH, DELETE) and automatically dispatches based on the contract's method field:

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

const client = wretch(BASE_URL)

// POST/PUT/PATCH request - body is required by the contract type
const responseBody1 = await sendByContract(client, somePostRouteDefinition, {
    pathParams: {
        userId: 1,
    },
    body: {
        isActive: true,
    },
})

// GET request - no body needed
const responseBody2 = await sendByContract(client, someGetRouteDefinition, {
    pathParams: {
        userId: 1,
    },
    queryParams: {
        id: 'testId',
    },
})

// DELETE request
const responseBody3 = await sendByContract(client, someDeleteRouteDefinition, {
    pathParams: {
        userId: 1,
    },
})

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

• body - request body (only applicable for payload routes, 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

Note: The individual sendByPayloadRoute, sendByGetRoute, and sendByDeleteRoute methods are deprecated in favor of sendByContract.

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