{"id":15451,"library":"kirbyup","title":"Kirby Panel Plugin Bundler","description":"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.","status":"active","version":"3.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/johannschopplich/kirbyup","tags":["javascript","kirby-cms","kirby-plugin","kirby","cli","panel","bundler","typescript"],"install":[{"cmd":"npm install kirbyup","lang":"bash","label":"npm"},{"cmd":"yarn add kirbyup","lang":"bash","label":"yarn"},{"cmd":"pnpm add kirbyup","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used in `kirbyup.config.ts` or `kirbyup.config.js` for custom configuration. Ensure to import from `kirbyup/config` specifically, not the root package.","wrong":"import { defineConfig } from 'kirbyup'","symbol":"defineConfig","correct":"import { defineConfig } from 'kirbyup/config'"},{"note":"While directly calling the binary works, it's best practice to define `kirbyup` commands in `package.json` scripts. Ensure your entry point is correct.","wrong":"node_modules/.bin/kirbyup serve src/index.js","symbol":"CLI Execution (npm script)","correct":"\"dev\": \"kirbyup serve src/index.js\""},{"note":"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.","wrong":"npx kirbyup serve src/index.js","symbol":"CLI Execution (npx)","correct":"npx kirbyup serve src/index.js"}],"quickstart":{"code":"{\n  \"name\": \"my-kirby-plugin\",\n  \"version\": \"1.0.0\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"dev\": \"kirbyup serve src/index.js\",\n    \"build\": \"kirbyup src/index.js\"\n  },\n  \"devDependencies\": {\n    \"kirbyup\": \"^3.4.1\"\n  }\n}\n// kirbyup.config.ts\nimport { defineConfig } from 'kirbyup/config'\nimport { resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst currentDir = fileURLToPath(new URL('.', import.meta.url))\n\nexport default defineConfig({\n  alias: {\n    // Example: Alias for Panel core components if you clone Kirby repo\n    '@/': `${resolve(currentDir, 'kirby/panel/src')}/`\n  },\n  vite: {\n    // Custom Vite options (e.g., add plugins)\n    css: {\n      preprocessorOptions: {\n        scss: { /* ... */ }\n      }\n    }\n  }\n})\n\n// src/index.js (your plugin entry point)\n// Example: A simple Vue component for your Kirby Panel plugin\nimport { createApp } from 'vue'\nimport MyPanelComponent from './components/MyPanelComponent.vue'\n\npanel.plugin('your/plugin', {\n  sections: {\n    'my-custom-section': {\n      component: MyPanelComponent,\n      props: ['headline']\n    }\n  }\n})\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=4.0.0-alpha"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.4.1"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"<3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: window is not defined"},{"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.","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.","error":"Vue 2 options (e.g., `data` as an object, `$children`, `$listeners`) are not working as expected in my Kirby Panel plugin."}],"ecosystem":"npm"}