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 project root, which are the two files Kirby loads.
Prerequisites
- Node.js 24 or newer with pnpm, npm or yarn.
- Kirby 6.0.0-beta.4 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:
Install kirbyup
pnpm add -D kirbyup@nextnpm install -D kirbyup@nextyarn add -D kirbyup@nextAdd the two scripts to package.json:
{
"scripts": {
"dev": "kirbyup dev src/index.js",
"build": "kirbyup src/index.js"
}
}Run Without Installing
npx -y kirbyup@next src/index.js works without a dependency. npx caches versions, so run npx -y kirbyup@next when the output looks stale. A dev dependency avoids the issue.
Write the Entry File
The entry file registers the plugin as usual:
// src/index.js
import DemoField from './components/DemoField.vue'
window.panel.plugin('my/plugin', {
fields: {
demo: DemoField,
},
})Import from vue as usual: kirbyup leaves it out of the bundle, and at runtime it resolves to the Panel's own copy, so your plugin and the Panel share one Vue.
Kirby loads the plugins one after another, so a top-level await in the entry file holds up the Panel until it settles. Keep slow work like a network request out of it.
A dynamic import() is bundled into index.js, as Kirby serves no other script for a plugin.
Start the Dev Server
npm run dev kirbyup v4.0.0-beta.2 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-CThe 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.* to .gitignore.
Watch Mode Without HMR
When the Panel cannot reach the dev server, for example on a remote host, rebuild on change instead:
kirbyup src/index.js --watch kirbyup v4.0.0-beta.2 building src/index.js
built in 20 ms
➜ Watching: src
➜ src/index.js changeWatch builds write an unminified index.dev.js and index.dev.css, which Kirby picks up the same way. Your index.css stays as the last production build left it.
Build for Production
npm run build kirbyup v4.0.0-beta.2 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 msindex.js and index.css land in the project root, minified. A leftover index.dev.js or index.dev.css is removed so Kirby uses the production files.