johannschopplich / kirby-vue-lightkit

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

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 Lightkit

Simple SPA for straightforward frontend projects
Explore the lightkit live »

Kirby + Vue.js Lightkit

Key Features

• ⚡️ Vue 3 & Vite
• 📦 Components auto importing
• 📑 Nuxt-inspired module system
• 🗂 File-based routing like Nuxt.js
• 🎨 UnoCSS – Instant on-demand atomic CSS engine
• 😃 Use icons from any icon sets, with no compromise
• 🔍 SEO-friendly: server-side generated meta tags

Introduction

Or jump right to the setup.

When your project uses a predefined folder structure which doesn't require adjustability by the user, this kit is for you.

It's aimed to be a straightforward Vue single-page application, while keeping Kirby in the background to deliver server-generated meta tags as well as backend-editing of content.

Think of this lightkit as the little brother of my Kirby + Vue.js Starterkit.

Why not use Vue.js with Kirby QL? Well, for some projects I don't like the idea of an API user which has complete read access to the panel. I want to control, what a user can fetch from the project. Hence, controllers.

🗂 File-Based Routing

File components in the src/pages directory correspond to the frontend's route structure. The Vue Router is automatically populated by generated routes using Vite's glob import.

Basic Routing

Pages will automatically map files from the pages directory to a route with the same name:

• src/pages/todo.vue -> /todo

Index Routes

Files named index are treated as the index page of a route:

• src/pages/index.vue -> /

Dynamic Routes

Dynamic routes are denoted using square brackets. Both directories and pages can be dynamic:

• src/pages/article/[id].vue -> /article/:id (/article/kirby-rocks)

Dynamic parameters will be passed to the page as props.

Catch-all Routes

Not found routes are denoted with square brackets containing an ellipsis:

• src/pages/[...all].vue -> /* (/non-existent-page)

The text after the ellipsis will be used both to name the route, and as the name of the prop in which the route parameters are passed.

Controllers for Data

• The site/controllers/default.php controller returns data which is embedded in the index template and available with the useSite() hook. Use it for data required for the first screen that's displayed to avoid a extra roundtrip.
• Every other controller can be called via the useController() hook. When fetched once from the network, it is then cached in store. Use it for data not required for the initial paint of your web application.

ℹ️ Note: Each controller has to return it's data nested inside the data key. Take a look into the examples provided to get an idea.

Folder Structure

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

Expand folder tree

kirby-vue-lightkit/
|
|   # 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/
|   ├── blueprints/
|   ├── config/
|   |
|   |   # Create data objects fetchable via the `useController()` hook
|   ├── controllers/
|   |   |
|   |   |   # Acts as global site object similar to Kirby's `$site`
|   |   └── default.php
|   |
|   └── templates/
|       |
|       |   # Index page and main entry point for the web application
|       └── default.php
|
|   # Includes all frontend-related sources
├── src/
|   |
|   |   # All components will be auto imported on-demand
|   ├── components/
|   |
|   |   # Composables for common actions
|   ├── composables/
|   |   |
|   |   |   # Fetch data of a controller by id
|   |   ├── useController.js
|   |   |
|   |   |   # Provides a object corresponding to Kirby's global `$site`
|   |   └── useSite.js
|   |
|   |   # File-based routing
|   ├── pages/
|   |
|   ├── App.vue
|   ├── index.css
|   ├── index.js
|   └── router.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

Prerequisites

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

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. To install them, run:

composer install

Node Dependencies

Install npm dependencies:

npm ci

Environment Variables

Duplicate the .env.example as .env::

cp .env.example .env

Optionally, adapt it's values.

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 either development or production 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` in 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.

License

MIT License © 2021-2023 Johann Schopplich