alova banner

Alova Client-Side Usage

For server-side (Node/Bun/Deno), see alova-server skill. For alova openapi usage, see alova-openapi skill.

How to Use This Skill

This skill is structured in two layers:

This file — Quick-reference index: what each API does and when to use it. Read this first.
Official docs (fetch on demand) — For full options, edge cases, or unfamiliar APIs, fetch the URL listed in each section to get the latest accurate information.

Always fetch the official doc before answering questions about specific API options or behaviors — alova is actively developed and live docs are more reliable than training data.

Installation & Setup

See references/SETUP.md for:

Installation
Creating Alova instance
Framework-specific StatesHook
Request adapters
Global request sharing and timeout
Create interceptor about Token-based login, logout and token refresh
cache logger
limit number of method snapshots

Create Method Instance

alova provides a total of 7 request types.

Instance creation function	Parameters
GET	`alovaInstance.Get(url[, config])`
POST	`alovaInstance.Post(url[, data[, config]])`
PUT	`alovaInstance.Put(url[, data[, config]])`
DELETE	`alovaInstance.Delete(url[, data[, config]])`
HEAD	`alovaInstance.Head(url[, config])`
OPTIONS	`alovaInstance.Options(url[, config])`
PATCH	`alovaInstance.Patch(url[, data[, config]])`

Parameter Description:

url is the request path;
data is the request body data;
config is the request configuration object, which includes configurations such as request headers, params parameters, request behavior parameters, etc.;

In fact, the above functions calling are not sending request, but creates a method instance, which is a PromiseLike instance. You can use then, catch, finally methods or await to send request just like a Promise object.

alovaInstance
  .Get('/api/user')
  .then((response) => {
    // ...
  })
  .catch((error) => {
    // ...
  })
  .finally(() => {
    // ...
  });

// or
try {
  await userMethodInstance;
} catch (error) {
  // ...
} finally {
  // ...
}

See Method Documentation if need to know full method instance API.

Method Metadata

Add additional information to specific method instances to facilitate their identification or additional information in global interceptor such as different response returning, global toast avoiding. please set method metadata. See -> Method Metadata.

Core Hooks

Use these hooks in components instead of hand-rolling common request patterns.

import from alova/client.

Hook	When to use	Docs
`useRequest`	Fetch on mount, or trigger once on a user action (button click, form submit)	Docs
`useWatcher`	Re-fetch automatically when reactive state changes (search input, filter, tab, page)	Docs
`useFetcher`	Preload data silently in background, or refresh from outside the component that owns the data	Docs

Business Strategy Hooks

import from alova/client.

Scenario	Hook	Key capability	Docs
Paginated list / infinite scroll	`usePagination`	Auto page management, preload next/prev, optimistic insert/remove/replace	Docs
Form submit (any complexity)	`useForm`	Draft persistence, multi-step state sharing, auto-reset	Docs
Polling / focus / reconnect refresh	`useAutoRequest`	Configurable triggers, throttle	Docs
Sms, email verification code send + countdown	`useCaptcha`	Cooldown timer built-in	Docs
Cross-component request trigger	`actionDelegationMiddleware` + `accessAction`	No prop-drilling or global store	Docs
Chained dependent requests	`useSerialRequest` / `useSerialWatcher`	Each step receives previous result	Docs
Retry with exponential backoff	`useRetriableRequest`	Configurable attempts + jitter	Docs
File upload with progress	`useUploader`	Concurrent limit, progress events	Docs
Server-Sent Events	`useSSE`	Reactive `data` + `readyState`	Docs
Seamless data interaction	`useSQRequest`	interact with UI can be responded immediately without waiting	Docs

Cache Strategy

Alova has L1 (memory) and L2 (persistent/restore) layers, plus automatic request sharing (dedup).

Set cache globally and scoped

Fast in-page access, resets on refresh, Survive page refresh / offline-first, disable cache -> See Cache mode.
Auto-invalidate after a mutation, hitSource on GET + name on mutation Method -> See Auto Invalidate Cache.
Manual invalidate -> See Manual invalidate.
Set & Query cache -> See Operate Cache.

Key rule: prefer hitSource auto-invalidation — it requires zero imperative code and decouples components.

Hooks Middleware

Middleware allows you to intercept and control request behavior in useHooks. Common scenarios include:

Ignoring requests under certain conditions
Transforming response data
Changing request method or forcing cache bypass
Error handling (capture or throw custom errors)
Controlling response delays
Modifying reactive states (loading, data, etc.)
Implementing request retry logic
Taking full control of loading state

For full middleware API and examples, see Request Middleware.

Mock Request

Setup mock data for specific requests. See Mock Request.

Best Practices

Create multiple alova instances for different domains, APIs, or environments.
Provide a folder that uniformly stores request functions, to keep your code organized.
prefer using hooks in components, directly call method instance in other places.
prefer binding hooks events with chain calling style, like useRequest(method).onSuccess(...).onError(...).

Common Pitfalls

Pitfall	Fix
`useWatcher` first arg is a Method instance	Always wrap: `() => method(state.value)`
`updateState` silently does nothing	Only works while owning component is mounted; use `setCache` otherwise
Cache ops called synchronously in v3	`await invalidateCache / setCache / queryCache`
`useWatcher` doesn't fetch on mount	Set `immediate: true`

TypeScript

Annotate the response shape on the Method instance — hooks infer from it automatically:

const getUser = (id: number) => alovaInstance.Get<User>(`/users/${id}`);
// or need to transform data.
const getUser = (id: number) =>
  alovaInstance.Get(`/users/${id}`, {
    transform(user: User) {
      return {
        ...user,
        name: user.lastName + ' ' + user.firstName,
      };
    },
  });

const { data } = useRequest(getUser(1)); // data: Ref<User>

📄 TypeScript docs

SSR Component Party

alova can manage APIs on both server and client, instead using different request solutions on the server and client sides respectively.

CSR

Generally, alova's hooks only work in client side.

// won't send request in server side.
useRequest(getUser(1));

Nextjs

directly await method instance in server components.

const App = async () => {
  const data = await alovaInstance.Get('/todo/list');
  // then ... code
  return <div>{...}</div>;
};
export default App;

Nuxt

Using await before alova's hooks keep states on both ends in sync, which is the same effect as useFetch.

const { data } = await useRequest(getUser(1));

Sveltekit

directly await method instance in +page.server.[j|ts].

/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
  return {
    list: alovaInstance.Get('/todo/list'),
  };
}

Custom Adapter

If all preset adapters not meet your needs, custom your own adapter.

Custom Method Key

Change cache, request sharing and state updating matching strategy by setting key. See Custom Method Key.

alova-client-usage