Skip to main content

Quick Start

example tip
  1. If you don't know about alova yet, it is highly recommended that you read the alova overview first.
  2. Want to try it out first? You can click here to try a simple example!

Install​

npm install alova --save

Alova combines the UI framework to make the request easier. You can use the use hook provided by alova to initiate a request, which will return stateful data related to multiple requests such as loading, and automatically manage it in alova them without having to maintain them yourself.

When using alova, please ensure that the UI framework meets the following version requirements:

  1. React: >= v16.8
  2. Vue: 2.7, 3.x
  3. Svelte: Any

Send a request using useRequest​

First create an alova instance, use this instance to create the corresponding method, and pass it to useRequest.

<template>
  <div v-if="loading">Loading...</div>
  <div v-else-if="error">{{ error. message }}</div>
  <span v-else>responseData: {{ data }}</span>
</template>

<script setup>
  import { createAlova, useRequest } from 'alova';
  import GlobalFetch from 'alova/GlobalFetch';
  import VueHook from 'alova/vue';

  // 1. Create an alova instance
  const alovaInstance = createAlova({
    // VueHook is used to create ref status, including request status loading, response data data, request error object error, etc.
    statesHook: VueHook,

    // request adapter, it is recommended to use the fetch request adapter
    requestAdapter: GlobalFetch(),

    // adapter GlobalFetch will return a Response instance
    // you can set a global response interception to return actual json data
    responded: response => response.json()
  });

  // 2. Use the alova instance to create a method and pass it to useRequest to send the request
  const { loading, data, error } = useRequest(
    alovaInstance.Get('https://jsonplaceholder.typicode.com/todos/1')
  );
</script>
Open on CodeSandboxOpen Sandbox

Use hook specification​

Please note that the use of useRequest needs to conform to the rules of use hook, that is, it can only be called at the outermost layer of the function. ❌❌❌ It is not recommended to call in loops, conditional judgments or sub-functions.

For example, the following usage example in the click callback, when used in the callback function, although the request can be initiated normally, the responsive data returned by the use hook cannot be used in the view, and the same is true for loops and conditional judgments.

// ❌ bad
const handleClick = () => {
  const { loading, data } = useRequest(getter);
};

// -------
// ✅ good
const { loading, data, send } = useRequest(getter, {
  immediate: false
});
const handleClick = () => {
  send();
};

Use the method instance to send the request​

The use hook can only be used to send requests within the component. Outside the component, you can directly send requests through the method instance.

const response = await alovaInstance.Get('https://api.alovajs.org/profile?id=1').send();

For more information about method instance sending request, please go to Use method instance to send request to read.

Regarding when to use useRequest to send a request and when to use a method instance to send a request, please read the Best Practice here.

Used in static html​

In addition to using esModule to install alova, you can also use <script> tags to use alova.

<!DOCTYPE html>
<html lang="en">
  <head>
    <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
    <script src="https://unpkg.com/alova/dist/alova.umd.min.js"></script>
    <script src="https://unpkg.com/alova/dist/adapter/globalfetch.umd.min.js"></script>
    <script src="https://unpkg.com/alova/dist/hooks/vuehook.umd.min.js"></script>
  </head>
  <body>
    <div id="app">
      <div v-if="loading">Loading...</div>
      <div v-else-if="error">{{ error.message }}</div>
      <span v-else>responseData: {{ data }}</span>
    </div>
  </body>
  <script>
    const alovaInstance = alova.createAlova({
      statesHook: VueHook,
      requestAdapter: GlobalFetch(),
      responded: response => response.json()
    });

    Vue.createApp({
      setup() {
        return alova.useRequest(
          alovaInstance.Get('https://jsonplaceholder.typicode.com/todos/1')
        );
      }
    }).mount('#app');
  </script>
</html>
Open on CodeSandboxOpen Sandbox

What to do next?​

In fact, this is just the simplest sample code, but alova also includes rich functions such as request and response interceptors, cache and state management, multiple core use hooks, etc., which we will elaborate in subsequent chapters.

If you want to better manage your request code, here is a best practice of method management, waiting for you to read it.

Is using alova in your project? please tell me!