If you're developing a plugin, you also need somewhere to test it, especially if it involves the Kirby panel. In other words, you need a sample Kirby site where your plugin can run. In this guide, you'll see how to set this up under a single Git repository.
You can follow along, but there will be a GitHub template at the end of the guide that you can use for your plugin and start right away!
To begin, we need to establish the base of our plugin first. The pluginkit is a very nice starting point:
This gives us the
index.php file that initializes our plugin:
package.json with npm scripts for kirbyup:
You don't have to install kirbyup locally or globally, since it will be fetched remotely once when running your first command. This may take a short amount of time.
Now, start kirbyup in watch mode by running the
dev npm script:
This will generate the following files in your repo:
...but how do you view them? You need a Kirby site to run the plugin.
First, we'll use Composer to install Kirby:
...and add some basic site files, like the default template and the home page:
The site can't work without its
index.php file, but this file already exists - it loads the plugin. Well, we'll simply create an index file with a different name:
In addition to the index file, we need the
.htaccess file so that all requests are pointed to that index file, which can load Kirby and let it handle the request.
We can use the
.htaccess file from the Kirby Plainkit and add a line so that it points to our newly crated
index.site.php, instead of
At this point, if you open the project folder on
localhost, you should see the Kirby site. Now we need to close the loop by loading our plugin in that site. We, of course, do that by loading it from the
plugin folder. Create the following file:
When Kirby loads, it will include this "fake" plugin, which in turn will load our actual plugin's
index.php that lies 3 folders up the directory tree. If your plugin depends on other plugins, feel free to install them as well!
The full directory structure should look like this:
When we publish our plugin, we don't want the files related to our test site to appear in the production version of the plugin that people will be putting in their sites. We can exclude whatever we want with the
To verify that, run the following command:
You should get a ZIP file with the following contents:
Later, when you create a new release of the plugin on GitHub, it should create an identical ZIP with only these files. There will be no trace of your test site in the final version of the plugin.
We managed to create a setup where we can develop and view our plugin from the same repository, while still providing just the necessary files on release.
To get started right away with the same setup, use this template repository.