Kirby Headless Starter

[!TIP] Send a request with a Authorization: Bearer test header to the live playground for an example response.

This starter kit provides a minimal setup for a headless Kirby site. It allows you to fetch JSON-encoded data from your Kirby site using either KQL or Kirby's default template system. Under the hood, it uses the Kirby Headless Plugin to provide a headless API.

This project works well with Nuxt KQL.

Example Projects

cacao-kit-frontend: 🍫 Best practice Nuxt and KQL starter for your headless Kirby CMS
kirby-nuxt-starterkit: 💚 Kirby's sample site – ported to Nuxt and Kirby Query Language

Key Features

🧩 Optional bearer token authentication for KQL and custom API endpoints
🧱 Resolve fields in blocks: UUIDs to file and page objects or any other field
⚡️ Cached KQL queries
🌐 Multi-language support for KQL queries
😵 Built-in CORS handling
🍢 Express-esque API builder with middleware support
🗂 Return JSON from templates instead of HTML

Setup

[!TIP] 📖 Read the documentation

Kirby-related dependencies are managed via Composer and located in the vendor directory. To install them, run:

composer install

Environment Variables

Duplicate the .env.development.example as .env and adjust its values:

cp .env.development.example .env

[!NOTE] Make sure to set the correct requesting origin instead of the wildcard KIRBY_HEADLESS_ALLOW_ORIGIN=* for your deployment.

Deployment

[!NOTE] See ploi-deploy.sh for exemplary deployment instructions.

Some hosting environments require uncommenting RewriteBase / in .htaccess to make site links work.