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 22 or newer with pnpm, npm or yarn.
  • Kirby 4 or newer. Kirby 4 and 5 run the Panel on Vue 2, and kirbyup 3 builds for that runtime.

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 serve src/index.js",
    "build": "kirbyup src/index.js"
  },
  "devDependencies": {
    "kirbyup": "^3.5.0"
  }
}

The entry file registers the plugin as usual:

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

window.panel.plugin('my/plugin', {
  sections: {
    demo: DemoSection,
  },
})
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 v3.4.1
ℹ Starting development server…
✔ Server is listening on :5177

The dev server writes index.dev.mjs 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.mjs 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 v3.4.1
◐ Building src/index.js
✔ Build successful
ℹ Watching for changes in src

Watch builds write an unminified index.js in place of the production bundle.

Production ​

bash
npm run build
kirbyup v3.4.1
◐ Building src/index.js
./index.js   0.77 kB / gzip: 0.40 KiB
./index.css  0.42 kB / gzip: 0.22 KiB
✔ Build successful

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