Skip to content

Kirby 3.7.5

Search
    Search by Algolia

    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.

    composer.json
    {
    "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"
    ]
}
    Since 3.7.0

    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?

    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