Cacao Kit (Frontend)

[!TIP] If internationalization is not a requirement for your project, you can check out the 🧱 branch without i18n.

If this is your first time building an application with Nuxt, I recommend taking a look into the 💚 Kirby Nuxt Starterkit first to get a basic understanding of this tech-stack. It is a port of the Kirby starter kit, built with Nuxt and KQL.

This repository provides a minimal but feature-rich Nuxt 3 starter kit. It fetches content from the 🍫 Cacao Kit backend, a headless Kirby instance. It is the evolved version of the Kirby Nuxt Starterkit and my best practice solution to build a Nuxt based frontend on top of Kirby CMS.

You can harness every feature Nuxt provides to build a server-side rendered application or even pre-render the content using Nuxt's static generation.

Key design decisions is a block-first approach. Meaning, you can use Kirby's page structure as the source of truth and don't have to replicate the page structure in Nuxt. All pages are rendered by the catch-all route. Of course, you don't have to stick with the block-first architecture. If it doesn't speak to you or if you need custom Kirby page blueprints with custom fields, you can always create Nuxt pages and query the content using KQL. See the pages/about.vue page for an example.

Key Features

[!NOTE] If i18n is not a requirement for your project, you can check out the 🧱 branch without i18n.

🌐 Internationalization with @nuxtjs/i18n
🏆 Motto: “Everything is a block” – Kirby blocks define what to render for each page
🛣️ All pages are rendered by the catch-all route by default (you can still create Nuxt pages)
🌌 Use Kirby's page structure as the source of truth
🫂 Kirby Query Language with nuxt-kql
🏛 Global site data similar to Kirby's $site
🔎 SSR generated SEO data
📐 Prettier & ESLint
🔢 Pre-configured VSCode settings

Usage

Prerequisites

Enable Corepack using corepack enable
Install dependencies using pnpm install
Adapt the relevant environment variables:

# Base URL of the Kirby backend
KIRBY_BASE_URL=
# Token for bearer authentication
# See https://github.com/johannschopplich/cacao-kit-backend#bearer-token
KIRBY_API_TOKEN=

Development

Start the development server using pnpm run dev
Visit localhost:3000

Production

Build the application for production with pnpm run build.

Check out the deployment documentation.

Cookbook

Static Hosting

You can use Nuxt's static generation to pre-render the content. This is especially useful if you want to host the application on a CDN or a static hosting service like Netlify.

How to Add a New Block

Given you have created the block in the Kirby backend, you can add it to the frontend by following these steps:

Create a new component in the components/Kirby/Block/ directory.
Add the new block to the components/Kirby/Blocks.vue component to make it available when rendering the block's field JSON data.

For example, let's say you have created a new block called NoteHeader and want to render it with the KirbyBlocks component:

<script setup lang="ts">
import {
+  LazyKirbyBlockNoteHeader,
} from '#components'

const blockComponents: Partial<Record<string, new () => ComponentPublicInstance>> = {
  // Custom blocks
+  'note-header': LazyKirbyBlockNoteHeader,
}
</script>

How to Bring Your Own Styling

This kit is written in semantic HTML and styled by the class-less CSS framework new.css. It is only used for the demo content. You can remove the framework by deleting the <Link /> tag in the app.vue component and start over with your own styling.

Deployment

Just like any other Nuxt application, the Cacao Kit can be deployed on a Node.js server, pre-rendered for static hosting, or deployed to serverless or edge (CDN) environments. Follow the deployment documentation to learn more.

This repository includes a netlify.toml file to deploy the application to Netlify. The recommended deployment provider is Cloudflare Pages, which doesn't require any additional configuration.

Deployment Previews

Cloudflare Pages 👉 cacao-kit.byjohann.dev (recommended)
Netlify 👉 cacao-kit.netlify.app

What's Kirby?

getkirby.com – Get to know the CMS.
Try it – Take a test ride with our online demo. Or download one of our kits to get started.
Documentation – Read the official guide, reference and cookbook recipes.
Issues – Report bugs and other problems.
Feedback – You have an idea for Kirby? Share it.
Forum – Whenever you get stuck, don't hesitate to reach out for questions and support.
Discord – Hang out and meet the community.
YouTube - Watch the latest video tutorials visually with Bastian.
Mastodon – Spread the word.
Instagram – Share your creations: #madewithkirby.

johannschopplich / cacao-kit-frontend

readme