Plugin best practices

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

Plugin with own classes

Basic Panel plugin

Panel plugin with components

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:

1. MAJOR version when you make incompatible API changes
2. MINOR version when you add functionality in a backwards compatible manner, and
3. 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:

1. What is the purpose of the plugin and who profits from using it?
2. How can the plugin be installed?
3. 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.
4. Are there any config settings? If so, what is each config setting good for?

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

• If applicable, publish a site showcasing your plugin with a live demo. On request, we will provide a free Kirby license for this purpose. Please send an email to support@getkirby.com with some details on your plugin and the intended contents of the site. If you already have the site ready, feel free to send us the link for a quicker review process.
• Create an new topic in the 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 by sending an email to support@getkirby.com with a link to your Git repository and a cover (cover image in 2:1 format or a short code snippet). But we will add a submit form in the future.
• Post about your plugin, mentioning @getkirby where applicable.
• …