A scaffolding tool for Koha plugins. Generates correct, working plugin code with interactive hook selection, API route composition, and version management.
init— Interactive plugin initialization: prompts for metadata, lets you pick from 50+ Koha hooks, generates the plugin module with working stubs, config file, manifest, templates, and.gitignoreadd— Incrementally add components: UI page templates, API routes (with controller generation), Node.js frontend projectsincrement— Semver-aware version bumping across config, module, and package.jsonpackage— Create.kpzfiles for Koha plugin installationktd— One-command deployment to KTD containers
The generated plugin code is standard Koha — no runtime dependency on this tool. You can stop using the scaffolder at any time and continue developing by hand.
git clone https://github.com/pders01/koha-plugin.git my-plugin
cd my-plugin && rm -rf .git && git init
carton install # or: cpanm --installdeps .
perl bin/koha-plugin.pl initSee the quickstart guide for the full walkthrough.
Install via Carton (recommended) or any CPAN client:
carton install
# or: cpanm --installdeps .The tool also works with globally installed modules or local::lib. Carton is not required.
just provides convenient shortcuts. Run just for available commands. Everything just does can also be done directly with perl bin/koha-plugin.pl.
Build a self-contained binary that needs no Perl setup on the target system:
just binary
# Binary at dist/koha-plugin- Quickstart — zero to working plugin in 5 minutes
- Command reference — all commands and options
- Hook reference — every Koha plugin hook with descriptions, return types, and groupings
- Vue Islands guide — Vue micro frontends in Koha plugins
- Writing a simple plugin — minimal example
- POD style guide — conventions for hook stubs
- Live Circ Feed example — full-featured demo plugin with API, Vue island, and polling
Patterns extracted from real plugins where Koha lacks a first-class hook. Each documents the current workaround and what native support would replace.
- Plugin permissions — granular sub-permissions under module bit 19, with
intranet_jslabel injection - Audit logging — flow plugin mutations into
action_logsfortools/viewlog.pl - Atomic transactions —
_txnhelper for multi-statement integrity under PlackAutoCommit=1 - Cron idempotency — reentrant
cronjob_nightlyviaaction_logssentinels - Additional fields — wire Koha's
additional_fieldsto plugin entities on the raw-DBI path (plugins that register a DBIx::Class schema inherit the mixin directly) - Koha taxonomies and calendar — consume AVs, patron categories, desks, library groups, calendar
- REST API extension —
openapi.json, controllers,x-koha-authorization, shared logic - UI conventions — sidebar,
page-section, DataTables, Bootstrap modals, light-DOM Lit - RRule recurrence — RFC 5545 subset for plugin scheduling
- Koha extension gaps — surveys subsystems that are internally extensible (messaging preferences, OPAC user menu, pages, AdditionalContents) but lack plugin wiring; sketches the smallest hooks that would close each gap
- Plugin i18n — JSON dictionaries shared between Perl helpers and bundled Lit components, with fallback to English source keys
- Cypress integration tests — running Cypress against ktd from a plugin tree, fixture helpers, memcached cache invalidation, runner script
- Module organization —
Lib::*helpers,Controllers/<Surface>/<Op>.pmper-op packages, numbered migration registry inLib::Schema - CI for plugins — GitHub Actions workflow against ktd, weekly Koha clone + image caches, ready-signal polling, tag-gated release
The tool reads plugin metadata from koha-plugin.yml (or koha-plugin.json):
name: "Koha::Plugin::Com::Example::MyPlugin"
author: "Your Name"
version: "0.1.0"
description: "What your plugin does"
minimum_version: "22.11.00.000"
maximum_version: ""
release_filename: "example-myplugin"
static_dir_name: "static"
date_authored: "2026-03-20"
date_updated: "2026-03-20"Legacy .env files are still supported. Migrate with koha-plugin migrate yml.
- LMSCloud plugin utils — shared utilities for database migrations, OPAC pages, and i18n
- Kitchen Sink plugin — reference implementation of every Koha plugin hook
Contributions welcome. Please use perltidy and perlimports with the shipped configuration files.
Ping me on Koha's Mattermost @paulderscheid.