useKql

Returns KQL query data. Uses an internal server route to proxy requests.

Query responses are cached by default between function calls for the same query based on a calculated hash.

Return Values

• data: the result of the asynchronous function that is passed in.
• refresh/execute: a function that can be used to refresh the data returned by the handler function.
• error: an error object if the data fetching failed.
• status: a string indicating the status of the data request:
  • idle: when the request has not started, such as:
    • when execute has not yet been called and { immediate: false } is set
    • when rendering HTML on the server and { server: false } is set
  • pending: the request is in progress
  • success: the request has completed successfully
  • error: the request has failed
• clear: a function that can be used to set data to undefined (or the value of options.default() if provided), set error to undefined, set status to idle, and mark any currently pending requests as cancelled.

By default, Nuxt waits until a refresh is finished before it can be executed again.

Caching

Two call sites asking for the same query share one entry and one round trip – see Caching Strategies.

Clear the cache for a specific query by calling the clear function. This will remove the cached data for the query and allow the next request to fetch the data from the server:

const { data, refresh, clear } = await useKql({ query: 'site' })

async function invalidateAndRefresh() {
  clear()
  await refresh()
}

Example

<script setup lang="ts">
const { data, refresh, error, status, clear } = await useKql({
  query: 'site',
  select: ['title', 'children']
})
</script>

<template>
  <div>
    <h1>{{ data?.result?.title }}</h1>
    <button @click="refresh()">
      Refresh
    </button>
  </div>
</template>

Allow Client Requests

WARNING

Authorization credentials will be publicly visible. Also, possible CORS issues ahead if the backend is not configured properly.

To fetch data directly from your Kirby instance without the Nuxt proxy, set the module option client to true:

// `nuxt.config.ts`
export default defineNuxtConfig({
  modules: ['nuxt-kirby'],

  kirby: {
    client: true
  }
})

Now, every useKql call reaches your Kirby instance directly, sent from the client:

const { data } = await useKql(query)

Type Declarations

function useKql<
  ResT extends KirbyQueryResponse<any, boolean> = KirbyQueryResponse,
  ReqT extends KirbyQueryRequest = KirbyQueryRequest
>(
  query: MaybeRefOrGetter<ReqT>,
  opts?: UseKqlOptions<ResT>
): AsyncData<ResT | undefined, NuxtError>

export type UseKqlOptions<T> = Omit<AsyncDataOptions<T>, 'watch'> & Pick<
  NitroFetchOptions<string>,
  | 'onRequest'
  | 'onRequestError'
  | 'onResponse'
  | 'onResponseError'
  | 'headers'
  | 'retry'
  | 'retryDelay'
  | 'retryStatusCodes'
> & {
  /**
   * Language code to fetch data for in multi-language Kirby setups.
   */
  language?: MaybeRefOrGetter<string>
  /**
   * Forward the visitor's cookies to Kirby, overriding the module's `forwardCookies`.
   *
   * @remarks
   * Such a request never reads from or writes to the server-side cache, since one stored response
   * is shared between all visitors.
   */
  forwardCookies?: boolean
  /**
   * Watch an array of reactive sources and auto-refresh the fetch result when they change.
   * Query and language are watched by default. You can completely ignore reactive sources by using `watch: false`.
   */
  watch?: MultiWatchSources | false
}

TIP

useKql infers all of Nuxt's useAsyncData options.