Getting Started

TIP

Want to jump right in? Choose one of the Starter Kits to get started with Nuxt Kirby in no time instead of starting from scratch.

Step 1: Install Nuxt Kirby

npx nuxt module add kirby

Step 2: Add the Module

Add nuxt-kirby to your Nuxt config:

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

Step 3: Set up Your Kirby Backend

Nuxt Kirby needs a Kirby instance to connect to. You have two options:

Option A: Kirby Headless Starter (Recommended)

Use the Kirby Headless Starter which includes token authentication and optimizations for headless usage.

Option B: Standard Kirby + KQL Plugin

Install the official Kirby KQL plugin on your existing Kirby instance.

Step 4: Configure Authentication

For the Kirby Headless Starter, enable token authentication:

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

  kirby: {
    auth: 'bearer' // Enable token-based authentication
  }
})

Set your environment variables in .env:

# Your Kirby instance URL
KIRBY_BASE_URL=https://your-kirby-site.com
KIRBY_API_TOKEN=your-secret-token

If you prefer a standard Kirby + KQL setup, you have to use basic authentication instead.

TIP

See the Authentication guide for more details on authentication methods and configuration options.

Step 5: Choose Your Data Fetching Method

Now you can start fetching data! Nuxt Kirby offers two approaches:

For Complex Content Queries (KQL)

<script setup lang="ts">
const { data } = await useKql({
  query: 'site',
  select: {
    title: true,
    children: {
      query: 'site.children',
      select: ['title', 'url']
    }
  }
})
</script>

<template>
  <div>
    <h1>{{ data?.result?.title }}</h1>
    <nav>
      <a
        v-for="page in data?.result?.children"
        :key="page.url"
        :href="page.url"
      >
        {{ page.title }}
      </a>
    </nav>
  </div>
</template>

For Simple Data Fetching (Direct API)

<script setup lang="ts">
const { data } = await useKirbyData('api/pages/blog')
</script>

<template>
  <div>
    <h1>{{ data?.result?.title }}</h1>
    <div v-html="data?.result?.text" />
  </div>
</template>

Next Steps

• Data Fetching Methods – Choose between KQL and the REST API.
• Multi-Language Sites – Fetch content per locale.
• Typed Query Results – Annotate a query so data carries its shape.
• Starter Kits – Ready-made templates to build on.
• API Reference – Every composable and type.