---
title: "app"
description: "Composables that need the Nuxt app context (#app) — the half of the package that runs in a Nuxt app but not in plain Vue."
canonical_url: "https://nuxt-convex-module.dev/api-reference/reference/app"
---
# app

Composables that need the Nuxt app context (`#app`) — the half of the
package that runs in a Nuxt app but not in plain Vue.

This module contains [useAsyncQuery](#useasyncquery) and its paginated form
[useAsyncPaginatedQuery](#useasyncpaginatedquery): server-rendered Convex data that upgrades
to a live subscription after hydration.

## Usage

**Default — auto-imported.** In any page, component or composable, call it
with no import; its types are auto-imported too:

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { data: messages, status } = useAsyncQuery(api.messages.list, {})
// `AsyncQueryStatus`, `AsyncQueryReturn`, … resolve without an import as well:
const label = (s: AsyncQueryStatus) => s === 'pending' ? 'Loading…' : ''
</script>
```

**Explicit import — this subpath.** For a project that turns auto-imports
off, a file outside the app's auto-import scope, or an editor that wants
the import spelled out:

```ts
import { useAsyncQuery } from 'nuxt-convex-module/app'
```

**Types.** From `#imports` (Nuxt's auto-import barrel) or from this subpath,
whichever your file already uses:

```ts
import type { AsyncQueryReturn } from '#imports'
import type { AsyncQueryReturn } from 'nuxt-convex-module/app'

const messages: AsyncQueryReturn<Doc<'messages'>[]> = useAsyncQuery(api.messages.list, {})
```

Before 1.0 the composable was auto-imported but reachable from no subpath,
so neither the explicit form nor the types could be written at all.

## Interfaces

### AsyncPaginatedQueryOptions

Defined in: [src/runtime/nuxt/composables/use-async-paginated-query.ts:31](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L31)

Options for [useAsyncPaginatedQuery](#useasyncpaginatedquery): `usePaginatedQuery`'s
`initialNumItems` plus the SSR options of [AsyncQueryOptions](#asyncqueryoptions).

#### Extends

- `Pick`<[`AsyncQueryOptions`](#asyncqueryoptions), `"key"` | `"server"` | `"lazy"` | `"token"`>

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Inherited from
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="initialnumitems">
        
      </a>
      
       <code>
        initialNumItems
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      How many items the first page holds — on the server and on the client.
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L33" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:33
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="key">
        
      </a>
      
       <code>
        key?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Key for the underlying <code>
        useAsyncData
      </code>
      
       entry (payload dedup across components). Defaults to a key derived from the query name and the initial args. Provide an explicit key when two call sites must not share a payload entry.
    </td>
    
    <td>
      <a href="#asyncqueryoptions">
        <code>
          AsyncQueryOptions
        </code>
      </a>
      
      .<a href="#key-1">
        <code>
          key
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L44" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:44
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="server">
        
      </a>
      
       <code>
        server?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Fetch the query on the server during SSR and embed the result in the Nuxt payload. Set <code>
        false
      </code>
      
       to fetch on the client only. <strong>
        Default
      </strong>
      
       <code>
        true
      </code>
    </td>
    
    <td>
      <a href="#asyncqueryoptions">
        <code>
          AsyncQueryOptions
        </code>
      </a>
      
      .<a href="#server-1">
        <code>
          server
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L51" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:51
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="lazy">
        
      </a>
      
       <code>
        lazy?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Mirror <code>
        useAsyncData
      </code>
      
      's <code>
        lazy
      </code>
      
       option: don't block client-side navigation on the initial fetch. <strong>
        Default
      </strong>
      
       <code>
        false
      </code>
    </td>
    
    <td>
      <a href="#asyncqueryoptions">
        <code>
          AsyncQueryOptions
        </code>
      </a>
      
      .<a href="#lazy-1">
        <code>
          lazy
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L58" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:58
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="token">
        
      </a>
      
       <code>
        token?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
      
       | (() => <code>
        string
      </code>
      
       | <code>
        Promise
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        null
      </code>
      
      > | <code>
        null
      </code>
      
      )
    </td>
    
    <td>
      JWT to authenticate the SSR fetch, or a function resolving one. Defaults to the token the Better Auth server plugin prefetched for this request (when that integration is enabled); pass a value here to integrate any other server-side auth source. The client-side live subscription authenticates through the Convex client's own <code>
        setAuth
      </code>
      
       wiring.
    </td>
    
    <td>
      <a href="#asyncqueryoptions">
        <code>
          AsyncQueryOptions
        </code>
      </a>
      
      .<a href="#token-1">
        <code>
          token
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L75" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:75
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### AsyncPaginatedQueryData

Defined in: [src/runtime/nuxt/composables/use-async-paginated-query.ts:42](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L42)

The reactive half of [AsyncPaginatedQueryReturn](#asyncpaginatedqueryreturn): `usePaginatedQuery`'s
fields plus the `error` and `refresh` of the Nuxt data contract.

#### Extended by

- [`AsyncPaginatedQueryReturn`](#asyncpaginatedqueryreturn)

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Item
      </code>
    </td>
  </tr>
</tbody>
</table>

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="results">
        
      </a>
      
       <code>
        results
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        Item
      </code>
      
      <span>
        
      </span>
      
      >
    </td>
    
    <td>
      The rows: the server-rendered first page until the live subscription delivers its own, then every loaded page, live. The server page is shown for the initial args only — after an args change the list is empty until the new first page arrives.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L49" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:49
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="status">
        
      </a>
      
       <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        "LoadingFirstPage"
      </code>
      
       | <code>
        "CanLoadMore"
      </code>
      
       | <code>
        "LoadingMore"
      </code>
      
       | <code>
        "Exhausted"
      </code>
      
      >
    </td>
    
    <td>
      <code>
        usePaginatedQuery
      </code>
      
      's status. Before the live subscription has its first page it is derived from the server page: <code>
        'CanLoadMore'
      </code>
      
       or <code>
        'Exhausted'
      </code>
      
      .
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L54" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:54
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isloading">
        
      </a>
      
       <code>
        isLoading
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      <code>
        true
      </code>
      
       while no page — server or live — is available yet, or more rows are loading.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L56" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:56
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="error">
        
      </a>
      
       <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        Error
      </code>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      The SSR fetch error or the live subscription's, <code>
        null
      </code>
      
       when none. Never thrown.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L58" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:58
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="loadmore">
        
      </a>
      
       <code>
        loadMore
      </code>
    </td>
    
    <td>
      (<code>
        numItems
      </code>
      
      ) => <code>
        void
      </code>
    </td>
    
    <td>
      Fetch <code>
        numItems
      </code>
      
       more rows. Takes effect once the live subscription has its first page (<code>
        status
      </code>
      
       no longer derived from the server page).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L63" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:63
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="refresh">
        
      </a>
      
       <code>
        refresh
      </code>
    </td>
    
    <td>
      (<code>
        opts?
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Re-run the server-side first-page fetch (client-side it is a no-op — the subscription is live).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L65" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:65
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### AsyncPaginatedQueryReturn

Defined in: [src/runtime/nuxt/composables/use-async-paginated-query.ts:74](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L74)

Result of [useAsyncPaginatedQuery](#useasyncpaginatedquery): awaitable like `useAsyncData`, and
the refs of [AsyncPaginatedQueryData](#asyncpaginatedquerydata).

#### Extends

- `PromiseLike`<[`AsyncPaginatedQueryData`](#asyncpaginatedquerydata)<`Item`>>.[`AsyncPaginatedQueryData`](#asyncpaginatedquerydata)<`Item`>

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Item
      </code>
    </td>
  </tr>
</tbody>
</table>

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Inherited from
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="results-1">
        
      </a>
      
       <code>
        results
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        Item
      </code>
      
      <span>
        
      </span>
      
      >
    </td>
    
    <td>
      The rows: the server-rendered first page until the live subscription delivers its own, then every loaded page, live. The server page is shown for the initial args only — after an args change the list is empty until the new first page arrives.
    </td>
    
    <td>
      <a href="#asyncpaginatedquerydata">
        <code>
          AsyncPaginatedQueryData
        </code>
      </a>
      
      .<a href="#results">
        <code>
          results
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L49" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:49
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="status-1">
        
      </a>
      
       <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        "LoadingFirstPage"
      </code>
      
       | <code>
        "CanLoadMore"
      </code>
      
       | <code>
        "LoadingMore"
      </code>
      
       | <code>
        "Exhausted"
      </code>
      
      >
    </td>
    
    <td>
      <code>
        usePaginatedQuery
      </code>
      
      's status. Before the live subscription has its first page it is derived from the server page: <code>
        'CanLoadMore'
      </code>
      
       or <code>
        'Exhausted'
      </code>
      
      .
    </td>
    
    <td>
      <a href="#asyncpaginatedquerydata">
        <code>
          AsyncPaginatedQueryData
        </code>
      </a>
      
      .<a href="#status">
        <code>
          status
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L54" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:54
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isloading-1">
        
      </a>
      
       <code>
        isLoading
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      <code>
        true
      </code>
      
       while no page — server or live — is available yet, or more rows are loading.
    </td>
    
    <td>
      <a href="#asyncpaginatedquerydata">
        <code>
          AsyncPaginatedQueryData
        </code>
      </a>
      
      .<a href="#isloading">
        <code>
          isLoading
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L56" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:56
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="error-1">
        
      </a>
      
       <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        Error
      </code>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      The SSR fetch error or the live subscription's, <code>
        null
      </code>
      
       when none. Never thrown.
    </td>
    
    <td>
      <a href="#asyncpaginatedquerydata">
        <code>
          AsyncPaginatedQueryData
        </code>
      </a>
      
      .<a href="#error">
        <code>
          error
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L58" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:58
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="loadmore-1">
        
      </a>
      
       <code>
        loadMore
      </code>
    </td>
    
    <td>
      (<code>
        numItems
      </code>
      
      ) => <code>
        void
      </code>
    </td>
    
    <td>
      Fetch <code>
        numItems
      </code>
      
       more rows. Takes effect once the live subscription has its first page (<code>
        status
      </code>
      
       no longer derived from the server page).
    </td>
    
    <td>
      <a href="#asyncpaginatedquerydata">
        <code>
          AsyncPaginatedQueryData
        </code>
      </a>
      
      .<a href="#loadmore">
        <code>
          loadMore
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L63" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:63
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="refresh-1">
        
      </a>
      
       <code>
        refresh
      </code>
    </td>
    
    <td>
      (<code>
        opts?
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Re-run the server-side first-page fetch (client-side it is a no-op — the subscription is live).
    </td>
    
    <td>
      <a href="#asyncpaginatedquerydata">
        <code>
          AsyncPaginatedQueryData
        </code>
      </a>
      
      .<a href="#refresh">
        <code>
          refresh
        </code>
      </a>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L65" rel="nofollow">
        src/runtime/nuxt/composables/use-async-paginated-query.ts:65
      </a>
    </td>
  </tr>
</tbody>
</table>

#### Methods

##### then()

```ts
then<TResult1, TResult2>(onfulfilled?, onrejected?): PromiseLike<TResult1 | TResult2>;
```

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1542

Attaches callbacks for the resolution and/or rejection of the Promise.

###### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
    
    <th>
      Default type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        TResult1
      </code>
    </td>
    
    <td>
      <a href="#asyncpaginatedquerydata">
        <code>
          AsyncPaginatedQueryData
        </code>
      </a>
      
      <<code>
        Item
      </code>
      
      >
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TResult2
      </code>
    </td>
    
    <td>
      <code>
        never
      </code>
    </td>
  </tr>
</tbody>
</table>

###### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        onfulfilled?
      </code>
    </td>
    
    <td>
      ((<code>
        value
      </code>
      
      ) => <code>
        TResult1
      </code>
      
       | <code>
        PromiseLike
      </code>
      
      <<code>
        TResult1
      </code>
      
      >) | <code>
        null
      </code>
    </td>
    
    <td>
      The callback to execute when the Promise is resolved.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onrejected?
      </code>
    </td>
    
    <td>
      ((<code>
        reason
      </code>
      
      ) => <code>
        TResult2
      </code>
      
       | <code>
        PromiseLike
      </code>
      
      <<code>
        TResult2
      </code>
      
      >) | <code>
        null
      </code>
    </td>
    
    <td>
      The callback to execute when the Promise is rejected.
    </td>
  </tr>
</tbody>
</table>

###### Returns

`PromiseLike`<`TResult1` | `TResult2`>

A Promise for the completion of which ever callback is executed.

###### Inherited from

```ts
PromiseLike.then
```

---

### AsyncQueryOptions

Defined in: [src/runtime/nuxt/composables/use-async-query.ts:37](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L37)

Options for [useAsyncQuery](#useasyncquery).

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="key-1">
        
      </a>
      
       <code>
        key?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Key for the underlying <code>
        useAsyncData
      </code>
      
       entry (payload dedup across components). Defaults to a key derived from the query name and the initial args. Provide an explicit key when two call sites must not share a payload entry.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L44" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:44
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="server-1">
        
      </a>
      
       <code>
        server?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Fetch the query on the server during SSR and embed the result in the Nuxt payload. Set <code>
        false
      </code>
      
       to fetch on the client only. <strong>
        Default
      </strong>
      
       <code>
        true
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L51" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:51
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="lazy-1">
        
      </a>
      
       <code>
        lazy?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Mirror <code>
        useAsyncData
      </code>
      
      's <code>
        lazy
      </code>
      
       option: don't block client-side navigation on the initial fetch. <strong>
        Default
      </strong>
      
       <code>
        false
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L58" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:58
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="live">
        
      </a>
      
       <code>
        live?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Upgrade to a live WebSocket subscription on the client. Set <code>
        false
      </code>
      
       for SSR + hydration <em>
        without
      </em>
      
       realtime updates — no WebSocket is opened for this query, and <a href="#refresh-2">
        refresh
      </a>
      
       becomes the way to get fresh data. <strong>
        Default
      </strong>
      
       <code>
        true
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L67" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:67
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="token-1">
        
      </a>
      
       <code>
        token?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
      
       | (() => <code>
        string
      </code>
      
       | <code>
        Promise
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        null
      </code>
      
      > | <code>
        null
      </code>
      
      )
    </td>
    
    <td>
      JWT to authenticate the SSR fetch, or a function resolving one. Defaults to the token the Better Auth server plugin prefetched for this request (when that integration is enabled); pass a value here to integrate any other server-side auth source. The client-side live subscription authenticates through the Convex client's own <code>
        setAuth
      </code>
      
       wiring.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L75" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:75
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### AsyncQueryReturn

Defined in: [src/runtime/nuxt/composables/use-async-query.ts:85](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L85)

Reactive result of [useAsyncQuery](#useasyncquery). Also awaitable — `await useAsyncQuery(...)` blocks until the initial fetch settles, like
`useAsyncData`.

#### Extends

- `PromiseLike`<[`AsyncQueryData`](#asyncquerydata)<`T`>>

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        T
      </code>
    </td>
  </tr>
</tbody>
</table>

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="data">
        
      </a>
      
       <code>
        data
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        T
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      The query result: the server-fetched value first, replaced by the live subscription's value once the client receives one. <code>
        undefined
      </code>
      
       while nothing has loaded (or while skipped).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L91" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:91
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="error-2">
        
      </a>
      
       <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        Error
      </code>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      The initial-fetch or live-subscription error, <code>
        null
      </code>
      
       when none.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L93" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:93
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="status-2">
        
      </a>
      
       <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<a href="#asyncquerystatus">
        <code>
          AsyncQueryStatus
        </code>
      </a>
      
      >
    </td>
    
    <td>
      Initial-fetch status. Live pushes don't churn it: once data exists it stays <code>
        'success'
      </code>
      
       unless the live subscription errors.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L98" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:98
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="refresh-2">
        
      </a>
      
       <code>
        refresh
      </code>
    </td>
    
    <td>
      (<code>
        opts?
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Re-run the one-shot fetch. With a live subscription (<code>
        live: true
      </code>
      
      ) the server already pushes updates, so this is mainly for retrying after an error; with <code>
        live: false
      </code>
      
       it is the way to get fresh data.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L104" rel="nofollow">
        src/runtime/nuxt/composables/use-async-query.ts:104
      </a>
    </td>
  </tr>
</tbody>
</table>

#### Methods

##### then()

```ts
then<TResult1, TResult2>(onfulfilled?, onrejected?): PromiseLike<TResult1 | TResult2>;
```

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1542

Attaches callbacks for the resolution and/or rejection of the Promise.

###### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
    
    <th>
      Default type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        TResult1
      </code>
    </td>
    
    <td>
      <a href="#asyncquerydata">
        <code>
          AsyncQueryData
        </code>
      </a>
      
      <<code>
        T
      </code>
      
      >
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TResult2
      </code>
    </td>
    
    <td>
      <code>
        never
      </code>
    </td>
  </tr>
</tbody>
</table>

###### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        onfulfilled?
      </code>
    </td>
    
    <td>
      ((<code>
        value
      </code>
      
      ) => <code>
        TResult1
      </code>
      
       | <code>
        PromiseLike
      </code>
      
      <<code>
        TResult1
      </code>
      
      >) | <code>
        null
      </code>
    </td>
    
    <td>
      The callback to execute when the Promise is resolved.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onrejected?
      </code>
    </td>
    
    <td>
      ((<code>
        reason
      </code>
      
      ) => <code>
        TResult2
      </code>
      
       | <code>
        PromiseLike
      </code>
      
      <<code>
        TResult2
      </code>
      
      >) | <code>
        null
      </code>
    </td>
    
    <td>
      The callback to execute when the Promise is rejected.
    </td>
  </tr>
</tbody>
</table>

###### Returns

`PromiseLike`<`TResult1` | `TResult2`>

A Promise for the completion of which ever callback is executed.

###### Inherited from

```ts
PromiseLike.then
```

## Type Aliases

### AsyncQueryStatus

```ts
type AsyncQueryStatus = "idle" | "pending" | "success" | "error";
```

Defined in: [src/runtime/nuxt/composables/use-async-query.ts:30](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L30)

Request status of a [useAsyncQuery](#useasyncquery) call — mirrors Nuxt's
`useAsyncData` statuses.

---

### AsyncQueryData

```ts
type AsyncQueryData<T> = Pick<AsyncQueryReturn<T>, "data" | "error" | "status" | "refresh">;
```

Defined in: [src/runtime/nuxt/composables/use-async-query.ts:113](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L113)

The reactive half of [AsyncQueryReturn](#asyncqueryreturn) — what `await useAsyncQuery(...)`
resolves to, and the shape to annotate a value passed on from the call site.

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        T
      </code>
    </td>
  </tr>
</tbody>
</table>

## Variables

### useConvexAsyncPaginatedQuery

```ts
const useConvexAsyncPaginatedQuery: <Query>(query, args, options) => AsyncPaginatedQueryReturn<PaginatedQueryItem<Query>> = useAsyncPaginatedQuery;
```

Defined in: [src/runtime/nuxt/composables/use-async-paginated-query.ts:237](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L237)

A paginated Convex query the Nuxt way: the first page is fetched during SSR
and hydrated from the payload, then [usePaginatedQuery](https://nuxt-convex-module.dev/api-reference/reference/client#usepaginatedquery) takes over on
the client — live rows and `loadMore`, no loading flash for the first page.

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Query
      </code>
      
       <em>
        extends
      </em>
      
       <a href="https://nuxt-convex-module.dev/api-reference/reference/client#paginatedqueryreference">
        <code>
          PaginatedQueryReference
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <code>
        Query
      </code>
    </td>
    
    <td>
      a <code>
        FunctionReference
      </code>
      
       for the public paginated query.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        args
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      < | <code>
        "skip"
      </code>
      
       | <a href="https://nuxt-convex-module.dev/api-reference/reference/client#paginatedqueryargs">
        <code>
          PaginatedQueryArgs
        </code>
      </a>
      
      <<code>
        Query
      </code>
      
      >>
    </td>
    
    <td>
      the query's arguments without <code>
        paginationOpts
      </code>
      
      , or <code>
        'skip'
      </code>
      
      . Accepts a ref, computed, or getter.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <a href="#asyncpaginatedqueryoptions">
        <code>
          AsyncPaginatedQueryOptions
        </code>
      </a>
    </td>
    
    <td>
      <a href="#asyncpaginatedqueryoptions">
        AsyncPaginatedQueryOptions
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`AsyncPaginatedQueryReturn`](#asyncpaginatedqueryreturn)<[`PaginatedQueryItem`](https://nuxt-convex-module.dev/api-reference/reference/client#paginatedqueryitem)<`Query`>>

An awaitable [AsyncPaginatedQueryReturn](#asyncpaginatedqueryreturn).

#### Example

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { results, status, loadMore } = useAsyncPaginatedQuery(
  api.messages.list,
  {},
  { initialNumItems: 20 },
)
</script>
```

The payload entry is keyed on the query name, the *initial* args and
`initialNumItems` (override with `options.key`). Client-side navigation does
not fetch a page over HTTP: the subscription opens straight away, and the
server page only matters for the first paint.

---

### useConvexAsyncQuery

```ts
const useConvexAsyncQuery: <Query>(query, args?, options) => AsyncQueryReturn<FunctionReturnType<Query>> = useAsyncQuery;
```

Defined in: [src/runtime/nuxt/composables/use-async-query.ts:317](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L317)

Load a Convex query the Nuxt way: fetched on the server during SSR,
hydrated through the Nuxt payload, then seamlessly upgraded to a live
WebSocket subscription on the client.

Compared to useQuery (which renders `undefined` during SSR and
fetches on the client), `useAsyncQuery` puts real data in the
server-rendered HTML and never refetches it on hydration — the live
subscription simply takes over. Compared to `preloadQuery` +
`usePreloadedQuery`, no server route or prop-threading is needed.

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Query
      </code>
      
       <em>
        extends
      </em>
      
       | <a href="https://nuxt-convex-module.dev/api-reference/reference/client#functionreference">
        <code>
          FunctionReference
        </code>
      </a>
      
      <<code>
        "query"
      </code>
      
      > | <a href="https://nuxt-convex-module.dev/api-reference/reference/client#functionreference_future">
        <code>
          FunctionReference_future
        </code>
      </a>
      
      <<code>
        "query"
      </code>
      
      >
    </td>
  </tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <code>
        Query
      </code>
    </td>
    
    <td>
      a <code>
        FunctionReference
      </code>
      
       for the public query to run, like <code>
        api.dir1.dir2.filename.func
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        args?
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      <<code>
        "skip"
      </code>
      
       | <a href="https://nuxt-convex-module.dev/api-reference/reference/client#functionargs">
        <code>
          FunctionArgs
        </code>
      </a>
      
      <<code>
        Query
      </code>
      
      >>
    </td>
    
    <td>
      The arguments to the query function, or <code>
        'skip'
      </code>
      
      . Accepts a ref, computed, or getter for reactive args.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="#asyncqueryoptions">
        <code>
          AsyncQueryOptions
        </code>
      </a>
    </td>
    
    <td>
      <a href="#asyncqueryoptions">
        AsyncQueryOptions
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`AsyncQueryReturn`](#asyncqueryreturn)<[`FunctionReturnType`](https://nuxt-convex-module.dev/api-reference/reference/client#functionreturntype)<`Query`>>

An awaitable [AsyncQueryReturn](#asyncqueryreturn) of `data` / `error` /
`status` refs and a `refresh` function.

#### Example

```vue
<script setup lang="ts">
import { api } from '#convex/api'

// SSR-rendered AND live:
const { data: tasks, status, error } = useAsyncQuery(api.tasks.list, { completed: false })

// SSR + hydration without a WebSocket (fetch-once pages):
const { data: stats, refresh } = useAsyncQuery(api.stats.summary, {}, { live: false })
</script>
```

The Nuxt payload entry is keyed on the query name and the *initial* args
(override with `options.key`). Reactive args are honored by the live
subscription; the payload only matters for first paint.

Pass `'skip'` as args (or a getter returning it) to pause the query — no
fetch runs and no subscription opens until args become real.

## Functions

### useAsyncPaginatedQuery()

```ts
function useAsyncPaginatedQuery<Query>(
   query, 
   args, 
   options
): AsyncPaginatedQueryReturn<PaginatedQueryItem<Query>>;
```

Defined in: [src/runtime/nuxt/composables/use-async-paginated-query.ts:110](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-paginated-query.ts#L110)

A paginated Convex query the Nuxt way: the first page is fetched during SSR
and hydrated from the payload, then [usePaginatedQuery](https://nuxt-convex-module.dev/api-reference/reference/client#usepaginatedquery) takes over on
the client — live rows and `loadMore`, no loading flash for the first page.

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Query
      </code>
      
       <em>
        extends
      </em>
      
       <a href="https://nuxt-convex-module.dev/api-reference/reference/client#paginatedqueryreference">
        <code>
          PaginatedQueryReference
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <code>
        Query
      </code>
    </td>
    
    <td>
      a <code>
        FunctionReference
      </code>
      
       for the public paginated query.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        args
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      < | <code>
        "skip"
      </code>
      
       | <a href="https://nuxt-convex-module.dev/api-reference/reference/client#paginatedqueryargs">
        <code>
          PaginatedQueryArgs
        </code>
      </a>
      
      <<code>
        Query
      </code>
      
      >>
    </td>
    
    <td>
      the query's arguments without <code>
        paginationOpts
      </code>
      
      , or <code>
        'skip'
      </code>
      
      . Accepts a ref, computed, or getter.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <a href="#asyncpaginatedqueryoptions">
        <code>
          AsyncPaginatedQueryOptions
        </code>
      </a>
    </td>
    
    <td>
      <a href="#asyncpaginatedqueryoptions">
        AsyncPaginatedQueryOptions
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`AsyncPaginatedQueryReturn`](#asyncpaginatedqueryreturn)<[`PaginatedQueryItem`](https://nuxt-convex-module.dev/api-reference/reference/client#paginatedqueryitem)<`Query`>>

An awaitable [AsyncPaginatedQueryReturn](#asyncpaginatedqueryreturn).

#### Example

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { results, status, loadMore } = useAsyncPaginatedQuery(
  api.messages.list,
  {},
  { initialNumItems: 20 },
)
</script>
```

The payload entry is keyed on the query name, the *initial* args and
`initialNumItems` (override with `options.key`). Client-side navigation does
not fetch a page over HTTP: the subscription opens straight away, and the
server page only matters for the first paint.

---

### useAsyncQuery()

```ts
function useAsyncQuery<Query>(
   query, 
   args?, 
   options?
): AsyncQueryReturn<FunctionReturnType<Query>>;
```

Defined in: [src/runtime/nuxt/composables/use-async-query.ts:160](https://github.com/qruto/nuxt-convex-module/blob/main/src/runtime/nuxt/composables/use-async-query.ts#L160)

Load a Convex query the Nuxt way: fetched on the server during SSR,
hydrated through the Nuxt payload, then seamlessly upgraded to a live
WebSocket subscription on the client.

Compared to useQuery (which renders `undefined` during SSR and
fetches on the client), `useAsyncQuery` puts real data in the
server-rendered HTML and never refetches it on hydration — the live
subscription simply takes over. Compared to `preloadQuery` +
`usePreloadedQuery`, no server route or prop-threading is needed.

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Query
      </code>
      
       <em>
        extends
      </em>
      
       | <a href="https://nuxt-convex-module.dev/api-reference/reference/client#functionreference">
        <code>
          FunctionReference
        </code>
      </a>
      
      <<code>
        "query"
      </code>
      
      > | <a href="https://nuxt-convex-module.dev/api-reference/reference/client#functionreference_future">
        <code>
          FunctionReference_future
        </code>
      </a>
      
      <<code>
        "query"
      </code>
      
      >
    </td>
  </tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <code>
        Query
      </code>
    </td>
    
    <td>
      a <code>
        FunctionReference
      </code>
      
       for the public query to run, like <code>
        api.dir1.dir2.filename.func
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        args?
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      <<code>
        "skip"
      </code>
      
       | <a href="https://nuxt-convex-module.dev/api-reference/reference/client#functionargs">
        <code>
          FunctionArgs
        </code>
      </a>
      
      <<code>
        Query
      </code>
      
      >>
    </td>
    
    <td>
      The arguments to the query function, or <code>
        'skip'
      </code>
      
      . Accepts a ref, computed, or getter for reactive args.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="#asyncqueryoptions">
        <code>
          AsyncQueryOptions
        </code>
      </a>
    </td>
    
    <td>
      <a href="#asyncqueryoptions">
        AsyncQueryOptions
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`AsyncQueryReturn`](#asyncqueryreturn)<[`FunctionReturnType`](https://nuxt-convex-module.dev/api-reference/reference/client#functionreturntype)<`Query`>>

An awaitable [AsyncQueryReturn](#asyncqueryreturn) of `data` / `error` /
`status` refs and a `refresh` function.

#### Example

```vue
<script setup lang="ts">
import { api } from '#convex/api'

// SSR-rendered AND live:
const { data: tasks, status, error } = useAsyncQuery(api.tasks.list, { completed: false })

// SSR + hydration without a WebSocket (fetch-once pages):
const { data: stats, refresh } = useAsyncQuery(api.stats.summary, {}, { live: false })
</script>
```

The Nuxt payload entry is keyed on the query name and the *initial* args
(override with `options.key`). Reactive args are honored by the live
subscription; the payload only matters for first paint.

Pass `'skip'` as args (or a getter returning it) to pause the query — no
fetch runs and no subscription opens until args become real.


## Sitemap

See the full [sitemap](https://nuxt-convex-module.dev/sitemap.md) for all pages.