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 out Cacao Kit, which is the evolved version of this starterkit. It uses Nuxt and KQL 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!
Kirby + Vue.js Starterkit
SPA with Vue 3 and Kirby: SEO-friendly, automatic routing, i18n and more!
Explore the starterkit live ยป
Kirby + Vue.js Starterkit
Key Features
- โก๏ธ 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
Alternatives
SPA
- kirby-vue-lightkit: โบ๏ธ Minimal Kirby + Vue starter: File-based routing, UnoCSS, SEO & more
SSR
- 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
Introduction
This boilerplate is a tight and comprehensive integration of Vue.js in the frontend and Kirby as headless CMS. The content is provided as JSON through Kirby and fetched by the frontend.
Folder Structure
Some notes about the folder structure with some additional comments on important files.
Expand folder tree
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
Caching
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.
Stale-While-Revalidate
The stale-while-revalidate mechanism for the usePage
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.
Prerequisites
- 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 a valid license.
Setup
Composer
Kirby-related dependencies are managed via Composer and located in the vendor
directory. Install them with:
composer install
Node Dependencies
Install npm dependencies:
npm ci
Environment Variables
Duplicate the .env.development.example
as .env
::
cp .env.development.example .env
Optionally, adapt it's values.
Vite will load .env
files according to the docs:
.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
Static assets
During development Kirby can't access static files located in the src
folder. Therefore it's necessary to create a symbolic link inside of the public folder:
ln -s $PWD/src/assets ./public/assets
Usage
Build Mode
During development a .lock
file will be generated inside the src
directory to let the backend now it runs in development mode. This file is deleted when running the build command.
โน๏ธ Alternatively, you can set a
KIRBY_MODE
env variable containing eitherdevelopment
orproduction
to set the app mode programmatically and overwrite the.lock
file mechanism. This may ease setups with Docker.
Development
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 with backend 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 on http://127.0.0.1:8080
by default, but you can adapt the location in your .env
file.
Production
Build optimized frontend assets to public/dist
:
npm run build
Vite will generate a hashed version of all assets, including images and fonts saved inside src/assets
. It will further create a manifest.json
file with hash records etc.
Deployment
โน๏ธ See ploi-deploy.sh for exemplary deployment instructions.
โน๏ธ Some hosting environments require to uncomment
RewriteBase /
in.htaccess
to make site links work.
Configuration
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 with
VITE_
are available in your code following theimport.meta.env.VITE_CUSTOM_VARIABLE
syntax.
For example, setting KIRBY_CACHE
to true
is useful in production environment.
Content API Slug
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 to
api
). If you insist on usingapi
for your content endpoint, you can rename Kirby's by adding aKIRBY_API_SLUG
key and set it to something other thanapi
.
Multi-Language
Multiple languages are supported. A comprehensive introduction about multi-language setups may be found on the Kirby website.
To enable language handling, you don't have to edit the config.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 Panel automatically renames all existing content and file meta data files and includes the language extension.
Language data is provided by the global site
object, which can be accessed via the useSite()
hook.
Stale-While-Revalidating
To keep page data fresh with stale-while-revalidate, set:
VITE_STALE_WHILE_REVALIDATE
totrue
Credits
- Huge thanks to arnoson for his Kirby Vite Plugin.
- Thanks to Jakub Medveckรฝ Heretik for his inspirational work on kirby-vue-starterkit which got me starting to build my own Kirby Vue integration.
License
MIT License ยฉ 2020-2023 Johann Schopplich