Kirby Nuxt Starter Kit

Kirby Nuxt Starter Kit is a demonstration boilerplate that ports Kirby CMS's official sample site to Nuxt, using the nuxt-kirby module to fetch content from a headless Kirby backend via Kirby Query Language (KQL).

What is the Kirby Nuxt Starter Kit?

The Kirby Nuxt Starter Kit is a Nuxt 3 frontend project created by Johann Schopplich. It takes a headless Kirby CMS instance (the Kirby Headless Starter) as its content source and produces a server-side rendered Nuxt website running on localhost:3000 in development. The repository is explicitly a demonstration; the author directs production users to the more advanced Cacao Kit instead. Setup requires just two environment variables: KIRBY_BASE_URL and KIRBY_API_TOKEN, plus a one-time pnpm install.

Key Features

• Kirby Query Language integration — Uses the nuxt-kirby module to query content directly from a headless Kirby backend with KQL.
• Component-based Kirby Blocks — Renders Kirby content blocks through Vue components located in components/Kirby/Block.
• Global site data plugin — Ships a plugins/site.ts with site-wide data accessible across the app, mirroring Kirby's $site.
• Pre-defined collections — Provides composables/collections.ts with reusable KQL query collections.
• SSR-generated SEO metadata — Server-side rendering emits SEO metadata automatically during page render.
• Prettier and ESLint — Code formatting and linting tools are configured out of the box.
• Pre-configured VSCode settings — Includes .vscode/settings.json with editor settings tuned for the project.
• Route pre-rendering — nuxt.config.ts includes a commented pre-render setup to address data-fetch latency.

Who is it for?

• Frontend developers — Build a Nuxt-based frontend for a Kirby CMS backend and see a complete reference implementation of KQL queries, blocks rendering, and SSR.
• Kirby CMS users — Explore how the official Kirby Starter Kit content maps to a headless Nuxt architecture without writing the integration from scratch.
• Technical evaluators — Compare this starter against Cacao Kit to decide which Nuxt + Kirby approach fits a production project.

What can you do with the Kirby Nuxt Starter Kit?

• Explore a working Nuxt + Kirby site — After corepack enable and pnpm install, run pnpm run dev to view the sample site at localhost:3000.
• Point it at your own Kirby backend — Set KIRBY_BASE_URL and KIRBY_API_TOKEN to your headless Kirby instance to serve your content through the same templates.
• Build a deployable app — Use pnpm run build to generate a production build of the Nuxt application for any supporting host.

How does the Kirby Nuxt Starter Kit work?

The starter fetches content by sending KQL queries to the configured Kirby backend inside Vue Suspense components. This ensures that page state is pre-rendered for both users and search engines. The cost is an additional 50–100 ms of initial server response time per KQL page query, which can be mitigated by pre-rendering routes as shown in nuxt.config.ts.

Alternatives

• Cacao Kit — A more advanced Nuxt frontend for Kirby CMS by the same author, recommended for production use instead of this demonstration starter.

FAQ

Are there any drawbacks?

Yes, data is fetched within Suspense components to guarantee pre-rendered output, which increases initial server response time by about 50–100 ms for the first KQL page query. The docs point to pre-rendering routes as a workaround.

What is Kirby?

Kirby is a CMS with a flexible file-based content model. The official website, documentation, forum, Discord, and YouTube channel are all linked from the repository's FAQ, making it easy to learn and get support.

Is this starter meant for production?

No. The repository banner explicitly states it is a demonstration and directs production users to Cacao Kit, which the author describes as a more advanced version and their best-practice solution for Nuxt frontends on Kirby CMS.

What setup is required?

You need to enable Corepack (corepack enable), install dependencies with pnpm install, and define the KIRBY_BASE_URL and KIRBY_API_TOKEN environment variables. Then pnpm run dev starts the development server at localhost:3000.