Skip to content

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 ​

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

Add the two scripts to package.json:

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:

js
// 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 ​

bash
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-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.* 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-beta.2  building src/index.js

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

Watch 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 ​

bash
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 ms

index.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.