The frontend infrastructure we keep rebuilding

Connecting a frontend to an API looks simple at first.

Call fetch, parse the response, and show the result.

Then the real requirements arrive. Requests need authentication. Expired tokens must be refreshed without sending several refresh requests at once. API errors need useful types. Pagination and filters need consistent serialisation. Concurrent edits need to be detected. Server state needs to work with the application’s query library.

None of these problems is unusual. That’s precisely why rebuilding them in every frontend is so frustrating.

I created Quilla Frontend Kit to turn those recurring foundations into small, composable TypeScript packages.

Infrastructure between your interface and your API

Quilla Frontend Kit isn’t a component library or frontend framework.

It sits lower in the application, between your product interface and the APIs it consumes. Its job is to provide consistent infrastructure for concerns such as:

• HTTP communication

• Authentication and token storage

• Single-flight token refresh

• Structured API errors

• Query-string serialisation

• Optimistic concurrency

• Server-state integrations

The toolkit is framework-agnostic at its core. Integrations with libraries such as React Query live in separate packages, so the underlying HTTP and authentication layers aren’t tied to React.

This means a project can adopt only the pieces it needs.

Why not create another API client inside the application?

A custom API client often begins as a small wrapper around fetch. Over time, it becomes one of the most important and least clearly defined parts of the frontend.

It accumulates retry behaviour, authentication rules, error translation, environment assumptions, response conventions, and framework-specific callbacks. Those decisions become difficult to test or reuse because they grew inside a particular application.

Quilla Frontend Kit separates those responsibilities.

Token storage is independent from the HTTP transport. Authentication decorates an HTTP client rather than being embedded inside it. Framework adapters depend on the core client, but the client doesn’t depend on a UI framework.

The result is infrastructure that can evolve without becoming a single application-specific abstraction.

Start with the smallest useful combination

For most projects, the common starting point is the API client, authentication, and error packages:

pnpm add @quilla-fe-kit/api-client @quilla-fe-kit/auth @quilla-fe-kit/errors

You can then create a client using the storage mechanism and refresh behaviour appropriate for your application:

import { createHttpClient } from '@quilla-fe-kit/api-client';
import { localStorageTokenStorage } from '@quilla-fe-kit/auth';

const httpClient = createHttpClient({
  baseUrl: 'https://api.example.com',
  storage: localStorageTokenStorage(),
  refreshEndpoint: async (refreshToken) => {
    const response = await fetch('https://api.example.com/auth/refresh', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${refreshToken}`,
      },
    });

    return response.json();
  },
});

This gives the application a configured HTTP boundary rather than scattering authentication and refresh behaviour across individual requests.

The toolkit also provides memory and cookie-based token-storage adapters. You can choose one based on your runtime and security model, or implement the storage interface yourself.

Adding React Query

Projects using TanStack React Query can add the separate adapter:

pnpm add @quilla-fe-kit/api-client-react-query @tanstack/react-query react

The adapter provides a client context, query foundations, mutation foundations, and retry behaviour based on the toolkit’s typed errors.

Keeping this integration separate is intentional. A project that doesn’t use React Query shouldn’t receive React-specific code or dependencies.

The same principle makes room for future adapters without changing the core HTTP client.

Designed for explicit API contracts

Quilla Frontend Kit has been designed to align naturally with Quilla Backend Kit, particularly around error responses, pagination, authentication, scope identity, and optimistic concurrency.

The projects remain independent. They share conventions, not runtime code.

That separation allows the frontend and backend to evolve independently while still agreeing on how information crosses the network.

Optimistic concurrency is a good example. The toolkit uses standard ETag and If-Match headers to carry numeric resource versions. If another user or process has changed a resource since it was loaded, the frontend can receive a structured conflict instead of silently overwriting the newer state.

The mechanics remain in the infrastructure layer, while the interface decides how to present and resolve the conflict.

Use it with an existing backend

You don’t need Quilla Backend Kit to use Quilla Frontend Kit.

The API client can communicate with any backend whose responses and authentication behaviour can be adapted to the client. Error parsing and query serialisation are configurable, and the authentication layer can wrap the transport without controlling it.

This is important because frontend infrastructure should not force a backend migration.

You can begin with one application boundary, configure it for your existing API, and gradually move request code behind it.

Who is it for?

Quilla Frontend Kit may be useful if you are:

• Maintaining a production SPA, SSR application, or React Native client

• Repeating authentication and token-refresh logic across projects

• Looking for consistent, typed API errors

• Using optimistic concurrency

• Integrating an API client with React Query

• Trying to keep transport concerns out of components and feature code

• Building frontends against multi-tenant APIs

It may be more infrastructure than a small application needs. A simple site with a few public requests might be better served by fetch alone.

The value appears when API communication becomes part of the application’s architecture rather than an occasional implementation detail.

Where the project stands

Quilla Frontend Kit is open source, ESM-only, and designed to work across browser, Node.js, and edge environments where the selected storage adapter is available.

It is currently pre-1.0, which means minor releases may contain breaking API changes while the packages mature.

If you recognise the infrastructure described here, take a look at the repository. Each package contains more detailed documentation, design decisions, and examples.

Explore Quilla Frontend Kit on GitHub →