kirbyup

Appearance

Getting Started ​

kirbyup bundles a Kirby Panel plugin with Vite. One command builds for production, one starts a dev server with hot module replacement.

Your source lives in src/, split into as many files as you like. kirbyup turns it into the index.js and index.css in the plugin root, which are the two files Kirby loads.

Prerequisites ​

  • Node.js 24 or newer with pnpm, npm or yarn.
  • Kirby 6.0.0-beta.1 or newer. Kirby 6 runs the Panel on Vue 3, and kirbyup 4 builds for that runtime. Plugins for Kirby 4 and 5 stay on kirbyup 3.x, documented at v3.kirbyup.getkirby.com.

Upgrading an existing plugin? Read the migration guide.

Starters

Skip the setup with one of the starters:

Installation ​

bash
pnpm add -D kirbyup
bash
npm install -D kirbyup
bash
yarn add -D kirbyup

Add the two scripts to package.json:

json
{
  "scripts": {
    "dev": "kirbyup dev src/index.js",
    "build": "kirbyup src/index.js"
  },
  "devDependencies": {
    "kirbyup": "^4.0.0"
  }
}

The entry file registers the plugin as usual:

js
// src/index.js
import DemoField from './components/DemoField.vue'

window.panel.plugin('my/plugin', {
  fields: {
    demo: DemoField,
  },
})
Run without installing

npx -y kirbyup src/index.js works without a dependency. npx caches versions, so run npx -y kirbyup@latest when the output looks stale. A dev dependency avoids the issue.

Development ​

bash
npm run dev
 kirbyup  v4.0.0-alpha.8  starting the development server

  ➜  Server:   http://localhost:5177
  ➜  Plugin:   index.dev.js
  ➜  Watching: ./**/*.php

  ready in 23 ms – open the Panel and your changes appear as you save
  stop with Ctrl-C

The dev server writes index.dev.js next to your plugin. Kirby loads that file instead of index.js and pulls the plugin from the dev server. Edit a component and the Panel updates in place. Changes to PHP files reload the page. Stop the server and the file is removed.

Add index.dev.js to .gitignore.

Watch mode without HMR

When the Panel cannot reach the dev server, for example on a remote host, rebuild on change instead:

bash
kirbyup src/index.js --watch
 kirbyup  v4.0.0-alpha.8  building src/index.js

  built in 20 ms
  ➜  Watching: src
  ➜  src/index.js change

Watch builds write an unminified index.dev.js, which Kirby picks up the same way.

Production ​

bash
npm run build
 kirbyup  v4.0.0-alpha.8  building src/index.js

  ➜  ./index.js   0.05 kB · gzip 0.07 kB
  ➜  ./index.css  0.02 kB · gzip 0.04 kB
  built in 22 ms

index.js and index.css land in the project root, minified. A leftover index.dev.js is removed so Kirby uses the production files.