βΊοΈ Minimal Kirby + Vue starter: File-based routing, UnoCSS, SEO & more
MIT License
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!
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 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.
Pages will automatically map files from the pages
directory to a route with the same name:
src/pages/todo.vue
-> /todo
Files named index
are treated as the index page of a route:
src/pages/index.vue
-> /
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.
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.
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.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.
Some notes about the folder structure with some additional comments on important files.
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
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.
Kirby-related dependencies are managed via Composer and located in the vendor
directory. To install them, run:
composer install
Install npm dependencies:
npm ci
Duplicate the .env.example
as .env
::
cp .env.example .env
Optionally, adapt it's values.
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
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.
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.
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.
βΉοΈ See ploi-deploy.sh for exemplary deployment instructions.
βΉοΈ Some hosting environments require to uncomment
RewriteBase /
in.htaccess
to make site links work.
MIT License Β© 2021-2023 Johann Schopplich