nuxt-kql
Kirby KQL module for Nuxt 3.
This module provides a useKql composable, which under the hood uses useFetch. Thus, KQL query fetching in your Nuxt 3 application will behave the same as Nuxt' internal data fetching and also infers its request caching!
Features
-
🤹 Handles authentication -
🪢 Supports token-based authentication with kirby-headless-starter (recommended) -
🍱 Built uponuseFetchcomposable -
🗃 Cached query responses -
🦾 Strongly typed
ℹ️ For the time being, the module will be available on the server and client. Thus, your username/password pair for the API authentication will be exposed. Please keep that in mind.
Setup
# pnpm
pnpm add -D nuxt-kql
# npm
npm i -D nuxt-kql
Usage
Add nuxt-kql to your Nuxt config:
// `nuxt.config.ts`
import { defineNuxtConfig } from 'nuxt'
export default defineNuxtConfig({
modules: [
'nuxt-kql',
],
})
Create a .env file in your project and add the following environment variables:
KIRBY_API_URL=https://kirby.example.com/api
KIRBY_API_USERNAME=your-username
KIRBY_API_PASSWORD=your-password
Token-Based Authentication
In combination with the kirby-headless-starter, you can use a bearer token for authentication.
// `nuxt.config.ts`
import { defineNuxtConfig } from 'nuxt'
export default defineNuxtConfig({
modules: [
'nuxt-kql',
],
kql: {
// Enable the token-based authentication
auth: 'bearer',
// Needed for the kirby-headless-starter custom KQL endpoint
endpoint: 'kql',
},
})
Set the following environment variables in your project's .env file:
KIRBY_API_URL=https://kirby.example.com/api
KIRBY_API_TOKEN=your-token
Data Fetching
Use the globally available useKql composable to fetch queries:
{{ data?.result?.title }}
{{ JSON.stringify(data?.result, undefined, 2) }}
<script setup lang="ts">
const { data, pending, refresh, error } = await useKql({
query: 'site',
select: {
title: 'site.title',
},
})
script>
<template>
<div>
<h1>{{ data?.result?.title }}</h1>
<pre>{{ JSON.stringify(data?.result, undefined, 2) }}</pre>
</div>
</template>
Options
export interface ModuleOptions {
/**
* Kirby API base URL, like `https://kirby.example.com/api`
* @default 'process.env.KIRBY_API_URL'
*/
url?: string
/**
* Kirby KQL API route path
* @default 'query'
*/
endpoint?: string
/**
* Authentication method
* Set to `none` to disable authentication
* @default 'basic'
*/
auth?: 'basic' | 'bearer' | 'none'
/**
* Token for bearer authentication
* @default 'process.env.KIRBY_API_TOKEN'
*/
token?: string
/**
* Username/password pair for basic authentication
* @default { username: process.env.KIRBY_API_USERNAME, password: process.env.KIRBY_API_PASSWORD }
*/
credentials?: {
username: string
password: string
}
}
Playground
Checkout the playground example.
Development
- Clone this repository
- Install dependencies using
pnpm install - Run
pnpm run dev:prepare - Start development server using
pnpm run dev
License
MIT License © 2022 Johann Schopplich
65 Dec 26, 2022
15 Dec 3, 2022
128 Jan 7, 2023
8 Dec 16, 2022
10 Dec 24, 2022
50 Dec 26, 2022
39 Jan 5, 2023
3 Sep 22, 2022
5 Nov 8, 2022