Plugin best practices
A collection of tips how to structure, name, tag, describe and promote your plugin
Now that you have learned a lot about plugins and have decided to start developing your own, here are some best practices that will make it easier for users to find and use your plugins, and also for you to maintain it and maybe even understand your own code later on 😉.
Structure
Basic plugins
plugins
pluginname
- index.php
Plugin with own classes
plugins
pluginname
lib
- MyClass.php
- index.php
- vendor
Basic Panel plugin
plugins
pluginname
- index.php
- index.js
- composer.json
Panel plugin with components
plugins
pluginname
src
assets
- styles.css
components
Fields
- Field.vue
Sections
- Section.vue
- ...
- index.js
- index.php
- index.js (auto-generated)
For more complex plugins, add other subfolders as required.
Add composer.json
Always add a composer.json file with basic information about your plugin, including the current version number, so that Kirby can use this information in the Panel's System view, and users can easily get information about your plugin with Kirby's plugin methods.
{
"name": "superwoman/superplugin",
"description": "Superwoman Demo Plugin",
"homepage:": "https://github.com/yourname/yourplugin"
"version": "1.0.0",
"license": "MIT",
"authors": [
{
"name": "Superwoman",
"email": "superwoman@example.com"
}
],
"support": {
"docs": "https://github.com/yourname/yourplugin/blob/main/README.md",
"source": "https://github.com/yourname/yourplugin"
}
}
Kirby uses the links in the homepage
, support.docs
or support.source
fields to create a link to your plugin in the Panel's System view. If a homepage
link is given, this is used, otherwise Kirby falls back to support.docs
and support.source
in this order.
Commenting
Comments help you and your users to understand your code even years later and they make it easier for other developers if they want to contribute to your plugin's development. Documenting comments will allow you to auto-generate documentation of your classes and methods (where applicable).
Naming
While you are free to name your plugin whatever you like, it makes sense to give your repo a name that immediately makes it clear that your plugin is for the Kirby CMS. Most developers name their repos kirby3-pluginname
or kirby-pluginname
.
The plugin name itself ideally reveals the purpose of the plugin.
Description
Add a good description to your plugin repo so that people looking for a specific plugin will immediately get what the plugin actually does.
Tagging
On GitHub, you can tag your plugins. Don't forget to add the following tags in addition to those that describe the purpose of your plugin:
- kirby3
- kirby-cms
- kirby-plugin
Versioning
Use semantic versioning:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backwards compatible manner, and
- PATCH version when you make backwards compatible bug fixes
Add a README
In your README, describe the plugin in every little detail and how to use it:
- What is the purpose of the plugin and who profits from using it?
- How can the plugin be installed?
- How can users use the plugin? Ideally, add step by step instructions, not just a few examples. This is particularly important if using the plugin requires some background knowledge or user code.
- Are there any config settings? If so, what is each config setting good for?
The easier you make it for users to use your plugin, the more likely they will actually use it, star it and maybe even buy you a beer or two.
Add a license
Don't forget to add the license under which your plugin is published and if it is free or commercial.
If it is free but you want people to donate, add a link to the platform where you want them to donate or offer some options.
Promote your plugin
- Create an new topic in the Kirby 3 plugins category on the forum, ping @texnixe to make sure she'll mention it in the next Kosmos issue.
- Submit it to the Kirby plugins directory, currently either by making a PR to the getkirby.com repo or by creating an issue, but we will add a submit form in the future.
- Tweet it mentioning @getkirby.
- …