kirbyup

Take a look into Kirby's pluginkit repository for an example setup.

The fastest and leanest way to bundle your Kirby Panel plugins. No configuration necessary.

Key Features

• 🍂 Lightweight, robust and tested
• ⚡️ Fast compilation with Vite/esbuild
• 🔄 Hot Module Replacement and watch mode (requires Kirby v3.7.4+)
• *️⃣ kirbyup.import to auto-import blocks & fields
• 🎒 PostCSS support
• 🧭 Path resolve aliases
• 🔌 Env variables support
• 🦔 Extendable configuration with kirbyup.config.js

Requirements

• Node 16 or newer

Get Started Right Away

… With one of the following Panel plugin kits:

• eslint-and-prettier (recommended)
• tailwindcss
• Kirby's default pluginkit

Installation

If you want to use kirbyup right away, there is no need to install it. Simply call it with npx:

{
  "scripts": {
    "dev": "npx -y kirbyup src/index.js --watch",
    "serve": "npx -y kirbyup serve src/index.js",
    "build": "npx -y kirbyup src/index.js"
  }
}

If npx doesn't use the latest kirbyup version, although it is available, run npx -y kirbyup@latest instead or delete the ~/.npm/_npx cache folder.

While kirbyup will stay backwards compatible, exact build reproducibility may be of importance to you. If so, I recommend targeting a specific package version, rather than using npx. Install kirbyup with a package manager of your choice locally to your project:

npm i kirbyup --save-dev

Example package configuration:

{
  "scripts": {
    "dev": "kirbyup src/index.js --watch",
    "serve": "kirbyup serve src/index.js",
    "build": "kirbyup src/index.js"
  },
  "devDependencies": {
    "kirbyup": "latest"
  }
}

Global installation is supported as well, but not recommended.

Usage

Development

Start a development server for the Panel plugin:

ℹ️ This feature requires Kirby v3.7.4+.

kirbyup serve src/index.js

This creates ./index.dev.mjs, telling Kirby to load the development version of the plugin from the dev server started by kirbyup serve, enhanced by features like hot module replacement and auto-reload.

If you prefer the watch mode to build a development bundle of the final Panel plugin or develop in an older version of Kirby (prior to 3.7.4), run:

kirbyup src/index.js --watch

Production

kirbyup src/index.js

The final panel plugin will be bundled, minified, and written into the current directory as ./index.js and ./index.css.

Built-in Features

PostCSS

If the project contains a valid PostCSS config (any format supported by postcss-load-config, e.g. postcss.config.js), it will be automatically applied to all imported CSS.

If no configuration file is found, kirbyup will apply two PostCSS plugins which the Kirby Panel uses as well to let you embrace the same functionality within your Panel plugins. The following PostCSS transforms are applied by kirbyup:

• postcss-logical lets you use logical, rather than physical, direction and dimension mappings in CSS, following the CSS Logical Properties and Values specification.
• postcss-dir-pseudo-class lets you style by directionality using the :dir() pseudo-class in CSS, following the Selectors specification. It gives you the same syntax Kirby uses for full compatibility with RTL localizations of the Panel.

Path Resolve Aliases

Import certain modules more easily by using the ~/ path alias. It will resolve to the directory of your input file, for example src when building kirbyup src/index.js.

Now, given a deeply nested component, instead of using relative paths when importing like so:

// Inside deeply nested module
import someUtility from '../../utils'

You can use the alias:

import someUtility from '~/utils'

ℹ️ You can use @/ as path alias as well.

Auto-Import Blocks and Fields

If you find yourself in the situation of needing to import multiple blocks or fields into your Panel plugin, you can use the kirbyup kirbyup.import function to ease the process.

Before:

import Foo from './components/blocks/Foo.vue'
import Bar from './components/blocks/Bar.vue'
import Maps from './components/blocks/Maps.vue'

window.panel.plugin('kirbyup/example', {
  blocks: {
    foo: Foo,
    bar: Bar,
    maps: Maps
  }
})

After:

import { kirbyup } from 'kirbyup/plugin'

window.panel.plugin('kirbyup/example', {
  blocks: kirbyup.import('./components/blocks/*.vue')
})

Env Variables

kirbyup exposes env variables on the special import.meta.env object. Some built-in variables are available in all cases:

• import.meta.env.MODE: {development | production} the mode kirbyup is running in.
• import.meta.env.PROD: {boolean} whether kirbyup is running in production.
• import.meta.env.DEV: {boolean} whether kirbyup is running in development (always the opposite of import.meta.env.PROD)

During production, these env variables are statically replaced. It is therefore necessary to always reference them using the full static string. For example, dynamic key access like import.meta.env[key] will not work.

.env Files

kirbyup (thanks to Vite) uses dotenv to load additional environment variables from the .env and .env.local files in your plugin's root directory.

Loaded env variables are also exposed to your source code via import.meta.env.

To prevent accidentally leaking env variables for distribution, only variables prefixed with KIRBYUP_ or VITE_ are exposed to your processed code. Take the following file as an example:

DB_PASSWORD=foobar
KIRBYUP_SOME_KEY=123

Only KIRBYUP_SOME_KEY will be exposed as import.meta.env.VITE_SOME_KEY to your plugin's source code, but DB_PASSWORD will not.

Extendable Configuration With kirbyup.config.js

Create a kirbyup.config.js or kirbyup.config.ts configuration file the root-level of your project to customize kirbyup.

import { resolve } from 'node:path'
import { defineConfig } from 'kirbyup/config'

export default defineConfig({
  alias: {
    '#deep/': `${resolve(__dirname, 'src/deep')}/`
  },
  extendViteConfig: {
    build: {
      lib: {
        name: 'myPlugin'
      }
    }
  }
})

alias

When aliasing to file system paths, always use absolute paths. Relative alias values will be used as-is and will not be resolved into file system paths.

extendViteConfig

You can build upon the defaults kirbup uses and extend the Vite configuration with custom plugins etc.

For a complete list of options, take a look at the Vite configuration options.

Options

Inspect all available options with kirbyup --help and kirbyup serve --help.

kirbyup <input>

--out-dir <dir>

The output directory to save the processed code into. Defaults to the current working directory.

--watch [path]

Enables watch mode. If no path is specified, kirbyup watches the folder of the input file. Repeat --watch for multiple paths.

kirbyup serve <input>

--port <port>

The port for the development server to run on. Defaults to 5177.

--out-dir <dir>

The output directory where the plugin file read by Kirby is saved. Defaults to the project root.

--watch <path>

Specifies additional files that should be watched for changes, with changes causing the page to reload. Repeat --watch for multiple paths.

💡 By default, kirbyup will watch all PHP files (./**/*.php) in the plugin directory and reload the page if it detects changes. Using --watch to set your own path overrides this setting, so you need to add the PHP glob explicitly if you want to keep the behavior: --watch ./my/files/* --watch ./**/*.php

--no-watch

Disables the default behavior of watching all PHP files for changes.

Credits

• Vite by Evan You and all of its contributors.
• EGOIST for his inspirational work on tsup.

License

MIT License © 2021-2023 Johann Schopplich

MIT License © 2022-2023 Jonas Kuske