kirby-vue-lightkit

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

kirby-vue-lightkit

★ 41 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> **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](https://github.com/johannschopplich/cacao-kit-frontend), 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!

<h3 align="center">Kirby + Vue.js Lightkit</h3>

Simple SPA for straightforward frontend projects 
 <a href="https://kirby-vue-lightkit.jhnn.dev">Explore the lightkit live »</a>

## Kirby + Vue.js Lightkit

### Key Features

- ⚡️ [Vue 3](https://github.com/vuejs/vue-next) & [Vite](https://vitejs.dev)
- 📦 [Components auto importing](./src/components/)
- 📑 [Nuxt-inspired module system](./src/modules/)
- 🗂 [File-based routing](./src/pages) like Nuxt.js
- 🎨 [UnoCSS](https://github.com/unocss/unocss) – Instant on-demand atomic CSS engine
- 😃 [Use icons from any icon sets, with no compromise](https://github.com/antfu/unplugin-icons)
- 🔍 SEO-friendly: server-side generated meta tags

### Introduction

> [Or jump right to the setup](#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](https://github.com/johannschopplich/kirby-vue3-starterkit).

Why not use Vue.js with [Kirby QL](https://github.com/getkirby/kql)? 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`](./site/controllers).

### 🗂 File-Based Routing

File components in the [`src/pages`](./src/pages) directory correspond to the frontend's route structure. The Vue Router is automatically populated by generated routes using [Vite](https://vitejs.dev)'s [glob import](https://vitejs.dev/guide/features.html#glob-import).

#### Basic Routing

Pages will automatically map files from the [`pages`](./src/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`](./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.

<details>
<summary>Expand folder tree</summary>

</details>

## 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](https://getkirby.com/buy).

## Setup

### Composer

Kirby-related dependencies are managed via [Composer](https://getcomposer.org) and located in the `vendor` directory. To install them, run:

```bash
composer install
```

### Node Dependencies

Install npm dependencies:

```bash
npm ci
```

### Environment Variables

Duplicate the [`.env.example`](.env.example) as `.env`::

```bash
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:

```bash
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:

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

Afterwards, visit the app in your browser: [`http://127.0.0.1:8080`](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](https://vitejs.dev/guide/backend-integration.html) 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`:

```bash
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](./scripts/ploi-deploy.sh) for exemplary deployment instructions.

> ℹ️ Some hosting environments require to uncomment `RewriteBase /` in [`.htaccess`](public/.htaccess) to make site links work.

## License

kirby-vue-lightkit

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README