Kirby Panel Plugin Bundler

3.4.1 · active · verified Tue Apr 21

kirbyup is a zero-configuration bundler specifically designed for Kirby Panel plugins. It streamlines the development and build process by leveraging Vite internally, providing fast Hot Module Replacement (HMR) during development and optimized production builds. The current stable version is 3.4.1, with active development progressing towards v4.0.0, which introduces significant breaking changes related to Vue 3 migration. Its primary differentiator is its tailored approach for the Kirby CMS ecosystem, abstracting away complex bundler configurations for panel developers and allowing them to focus on plugin logic rather than build tooling. The project exhibits a steady release cadence, marked by regular updates and ongoing alpha releases for its next major version. It supports Node.js environments version 18 and above and ships with TypeScript types, facilitating modern JavaScript and TypeScript development workflows for Kirby plugins.

Common errors

```
ReferenceError: window is not defined
```
cause This error typically occurs in Node.js environments when browser-specific APIs (like `window`) are accessed, often due to a dependency issue, particularly with `c12` prior to v3.4.1.

fix Update `kirbyup` to v3.4.1 or higher. If using `npx`, ensure you specify `@latest` (`npx -y kirbyup@latest`) or install `kirbyup` as a local dev dependency and use `npm run` scripts.
```
Vue 2 options (e.g., `data` as an object, `$children`, `$listeners`) are not working as expected in my Kirby Panel plugin.
```
cause You are likely using a `kirbyup` v4.0.0-alpha release, which has migrated to Vue 3. Vue 3 has numerous breaking changes from Vue 2, causing incompatibility with older plugin code.

fix Migrate your Kirby Panel plugin's Vue components and related logic from Vue 2 to Vue 3 syntax and APIs. Consult the official Vue 3 Migration Guide for a comprehensive list of changes, including updates to global APIs, template directives, and instance properties.

Warnings

breaking kirbyup v4.0.0-alpha introduces a breaking change by migrating to Vue 3. This means any existing Kirby Panel plugins built with Vue 2 will require updates to be compatible, including changes to Vuex usage, global APIs, template directives, and removed instance properties like `$children` and `$listeners`.
Fix: Review the official Vue 3 Migration Guide and update your plugin's Vue components, store logic (if using Vuex), and API interactions. Be aware of removed options and restructured global APIs.
gotcha When invoking `kirbyup` via `npx`, particularly with older Node.js versions or specific configurations, users might encounter `ReferenceError: window is not defined`. This was addressed in v3.4.1 by pinning the `c12` dependency.
Fix: Ensure `kirbyup` is updated to at least v3.4.1. If still using `npx`, consider installing `kirbyup` as a development dependency (`npm install -D kirbyup`) or explicitly calling `npx -y kirbyup@latest` to ensure the latest version is used and to bypass potential `npx` caching issues.
gotcha `kirbyup` requires Node.js version 18 or higher. Using older Node.js versions will result in installation failures or runtime errors due to incompatible JavaScript features or dependencies.
Fix: Upgrade your Node.js environment to version 18 or newer. Use a Node Version Manager (like `nvm`) for easy switching and management of Node.js versions.
gotcha Using `npx` to run `kirbyup` can sometimes lead to cached outdated versions, even if a newer version is available. This might prevent you from accessing the latest features or bug fixes.
Fix: To ensure the latest version, install `kirbyup` as a dev dependency (`npm install -D kirbyup`) and use npm scripts (e.g., `npm run dev`), or explicitly specify `@latest` when using `npx` (e.g., `npx -y kirbyup@latest serve src/index.js`). You might also need to clear the `~/.npm/_npx` cache.

Install

npm install kirbyup npm
yarn add kirbyup yarn
pnpm add kirbyup pnpm

Imports

defineConfig
wrong:
```
import { defineConfig } from 'kirbyup'
```
correct:
```
import { defineConfig } from 'kirbyup/config'
```
Used in `kirbyup.config.ts` or `kirbyup.config.js` for custom configuration. Ensure to import from `kirbyup/config` specifically, not the root package.
CLI Execution (npm script)
wrong:
```
node_modules/.bin/kirbyup serve src/index.js
```
correct:
```
"dev": "kirbyup serve src/index.js"
```
While directly calling the binary works, it's best practice to define `kirbyup` commands in `package.json` scripts. Ensure your entry point is correct.
CLI Execution (npx)
wrong:
```
npx kirbyup serve src/index.js
```
correct:
```
npx kirbyup serve src/index.js
```
When using `npx`, it's recommended to add `-y` for non-interactive execution and `@latest` (e.g., `npx -y kirbyup@latest`) if you suspect caching issues, as `npx` may cache older versions.

Quickstart

Demonstrates `kirbyup` setup with a `package.json`, a `kirbyup.config.ts` for custom Vite configuration and path aliases, and a basic plugin entry point in `src/index.js` for a Kirby Panel section.

{
  "name": "my-kirby-plugin",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "kirbyup serve src/index.js",
    "build": "kirbyup src/index.js"
  },
  "devDependencies": {
    "kirbyup": "^3.4.1"
  }
}
// kirbyup.config.ts
import { defineConfig } from 'kirbyup/config'
import { resolve } from 'node:path'
import { fileURLToPath } from 'node:url'

const currentDir = fileURLToPath(new URL('.', import.meta.url))

export default defineConfig({
  alias: {
    // Example: Alias for Panel core components if you clone Kirby repo
    '@/': `${resolve(currentDir, 'kirby/panel/src')}/`
  },
  vite: {
    // Custom Vite options (e.g., add plugins)
    css: {
      preprocessorOptions: {
        scss: { /* ... */ }
      }
    }
  }
})

// src/index.js (your plugin entry point)
// Example: A simple Vue component for your Kirby Panel plugin
import { createApp } from 'vue'
import MyPanelComponent from './components/MyPanelComponent.vue'

panel.plugin('your/plugin', {
  sections: {
    'my-custom-section': {
      component: MyPanelComponent,
      props: ['headline']
    }
  }
})

view raw JSON →