Repository files navigation

Note

Thank you to everyone who has used this starterkit in the past. I'm grateful that something built for myself has been useful to others. I have moved from Vue to Nuxt for my projects and will not be maintaining this starterkit actively anymore. It is stable, but be aware.

I recommend to check outCacao Kit, which is the evolved version of this starterkit. It usesNuxt andKQL with a headless Kirby setup. It is my best practice starterkit for your next project with server-side rendering. All features of this starterkit are included!

SPA with Vue 3 and Kirby: SEO-friendly, automatic routing, i18n and more!
Explore the starterkit live »

• ⚡️Vue 3 &Vite
• 🛣 Automatic routing
• 📦On-demand components auto importing
• 📑Nuxt-inspired module system
• 🔍 SEO-friendly:server-side generated meta tags
• 🌐Multi-language support
• ♿ Accessible frontend routing
• 💫Stale-while-revalidate page data

• kirby-vue-lightkit: ⛺️ Minimal Kirby + Vue starter: File-based routing, UnoCSS, SEO & more

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

Or jump right to the setup.

This boilerplate is a tight and comprehensive integration ofVue.js in the frontend andKirby as headless CMS. The content is provided as JSON through Kirby and fetched by the frontend.

Some notes about the folder structure with some additional comments on important files.

kirby-vue3-starterkit/||# Main entry point of the website, point your web server to this directory├── public/||||# Frontend assets generated by Vite (not tracked by Git)|   ├── dist/||||# Static images like icons|   ├── img/||||# Kirby's media folder for thumbnails and more (not tracked by Git)|   └── media/||# Kirby's core folder containing templates, blueprints, etc.├── site/|   ├── config/||||||# General configuration settings for Kirby and plugins||   ├── config.php||||||# Builds a JSON-encoded `site` object for the frontend|||# Used by Vue Router to populate routes, but can be extended by commonly used data||   └── app-site.php||||# Only relevant in multi-language setups|   ├── languages/|||   ├── plugins/kirby-vue-kit/||||||# Core of the Vite integration plugin, mainly registers routes||   ├── index.php||||||# Routes to handle `.json` requests and serving the `index.php` snippet||   └── routes.php||||# Templates for JSON content representations fetched by frontend||# Contains also index page (`_app-index.php`)|   └── templates/||||# Handles build asset paths, inlines the `site` object, includes SEO meta tags, etc.|       └── _app-index.php||# Includes all frontend-related sources├── src/||||# `Header`, `Footer`, `Intro` and other components (auto imported on-demand)|   ├── components/||||# Composables for common actions|   ├── composables/||||||# Announces any useful information for screen readers||   ├── useAnnouncer.js||||||# Provides information about the current language||   ├── useLanguages.js||||||# Retrieves pages from the content API||   ├── useKirbyApi.js||||||# Returns page data for the current path, similarly to Kirby's `$page` object||   ├── usePage.js||||||# Returns a object corresponding to Kirby's global `$site`||   └── useSite.js||||# Modules system entries will be auto installed|   ├── modules/||||||# Installs the `v-kirbytext` directive to handle internal page links inside KirbyText||   ├── kirbytext.js||||||# Initializes the Vue Router||   └── router.js||||# Vue.js views corresponding to Kirby templates||# Routes are being automatically resolved|   ├── views/|||   ├── App.vue|   ├── index.css|   └── index.js||# Contains everything content and user data related (not tracked by Git)├── storage/|   ├── accounts/|   ├── cache/|   ├── content/|   ├── logs/|   └── sessions/||# Kirby CMS and other PHP dependencies (handled by Composer)├── vendor/||# Environment variables for both Kirby and Vite (to be duplicated as `.env`)├── .env.example||# Configuration file for Vite└── vite.config.js

The frontend will store pages between individual routes/views. When the tab get reloaded, the data for each page is freshly fetched from the API once again.

The stale-while-revalidate mechanism for theusePage hook allows you to respond as quickly as possible with cached page data if available, falling back to the network request if it's not cached. The network request is then used to update the cached page data – which directly affects the view after lazily assigning changes (if any), thanks to Vue's reactivity.

• Node.js with npm (only required to build the frontend)
• PHP 8.0+

Kirby is not a free software. You can try it for free on your local machine but in order to run Kirby on a public server you must purchase avalid license.

Kirby-related dependencies are managed viaComposer and located in thevendor directory. Install them with:

composer install

Install npm dependencies:

npm ci

Duplicate the.env.development.example as.env::

cp .env.development.example .env

Optionally, adapt it's values.

Vite will load.env files according to thedocs:

.env                # loaded in all cases.env.local          # loaded in all cases, ignored by git.env.[mode]         # only loaded in specified mode.env.[mode].local   # only loaded in specified mode, ignored by git

During development Kirby can't access static files located in thesrc folder. Therefore it's necessary to create a symbolic link inside of the public folder:

ln -s$PWD/src/assets ./public/assets

During development a.lock file will be generated inside thesrc directory to let the backend now it runs in development mode. This file is deleted when running the build command.

ℹ️ Alternatively, you can set aKIRBY_MODE env variable containing eitherdevelopment orproduction to set the app mode programmatically and overwrite the.lock file mechanism. This may ease setups with Docker.

You can start the development process with:

# Runs `npm run kirby` parallel to `vite`npm run dev

Afterwards visit the app in your browser:http://127.0.0.1:8080

For Valet users: Of course you can use a virtual host alternatively!

Vite is used in combination withbackend integration and only serves frontend assets, not the whole app. Thus,http://localhost:3000 won't be accessible.

The backend is served by the PHP built-in web server onhttp://127.0.0.1:8080 by default, but you can adapt the location in your.env file.

Build optimized frontend assets topublic/dist:

npm run build

Vite will generate a hashed version of all assets, including images and fonts saved insidesrc/assets. It will further create amanifest.json file with hash records etc.

ℹ️ Seeploi-deploy.sh for exemplary deployment instructions.

ℹ️ Some hosting environments require to uncommentRewriteBase / in.htaccess to make site links work.

All development and production related configurations for both backend and frontend code are located in your.env file:

• KIRBY_DEV_HOSTNAME andKIRBY_DEV_PORT specify the address where you wish the Kirby backend to be served from. It is used by the frontend to fetch content data as JSON.
• Keys starting withVITE_ are available in your code following theimport.meta.env.VITE_CUSTOM_VARIABLE syntax.

For example, settingKIRBY_CACHE totrue is useful in production environment.

To change the API slug to fetch JSON-encoded page data from, set

• KIRBY_CONTENT_API_SLUG to a value of your liking (defaults toapp). It can even be left empty to omit a slug altogether!

You can't use Kirby's internal API slug (defaults toapi). If you insist on usingapi foryour content endpoint, you can rename Kirby's by adding aKIRBY_API_SLUG key and set it to something other thanapi.

Multiple languages are supported. A comprehensive introduction aboutmulti-language setups may be found on the Kirby website.

To enable language handling, you don't have to edit theconfig.php manually. Just set

• KIRBY_MULTILANG totrue.
• KIRBY_MULTILANG_DETECT totrue (optional but recommended).

Then, visit the panel and add new languages by your liking. The Panelautomatically renames all existing content and file meta data files and includes the language extension.

Language data is provided by the globalsite object, which can be accessed via theuseSite() hook.

To keep page data fresh withstale-while-revalidate, set:

• VITE_STALE_WHILE_REVALIDATE totrue

• Huge thanks toarnoson for hisKirby Vite Plugin.
• Thanks to Jakub Medvecký Heretik for his inspirational work onkirby-vue-starterkit which got me starting to build my own Kirby Vue integration.

MIT License © 2020-2023Johann Schopplich