The Ktor Plugin Registry Has Launched!
Ktor uses plugins to give you fine-grained control over the functionality included in your application. Until now, third-party plugins were managed differently from those provided by the Ktor team. This was a barrier to growth for the Ktor ecosystem.
Earlier this month, in the Ktor 2024 product roadmap, we announced our Ktor Plugin Registry. This registry is now available. It enables the submission of community-based plugins to the Ktor team, categorizes plugins for easy searching, and provides users with essential documentation.
Introduction
At the moment you can build a Ktor project via the online project generator, picking the best mix of plugins for the task at hand. As shown below you can view and search for plugins by both name and category. When you click on a plugin its description is displayed to the right. This description includes examples of the code that will be added to your application.
When you hit the Add button the plugin is included in the project, along with any required dependencies. In this case, we include the Thymeleaf templating plugin, which in turn requires the Routing plugin. You can use the link beside the Generate project button to view all the plugins that have been added and remove any if necessary.
Despite the power and flexibility that this setup provides, there was one significant limitation. The project generator would only allow you to choose plugins produced by the Ktor team.
There are many excellent plugins provided by the wider Ktor community, but these had to be manually incorporated into projects and there was no way for community-based plugins to be offered as options within the Ktor project generator.
Thanks to the plugin registry, it is now possible for any team to submit their plugins for inclusion in the project generator. The registry itself does not contain the source code for community plugins. Instead, it holds a set of resources that describe each plugin and indicate where its source code is located. Using these resources, the Ktor team can obtain, evaluate, and incorporate the plugin for general use.
How to submit your plugin
In order to submit a plugin, you must first fork and clone the repository, then add the resources to a subfolder of the Plugins directory, and finally submit your changes as a pull request. The resources are made up of five separate files – three YAML, one markdown, and one Kotlin. Examples of each of these can be found in the Templates folder in the registry.
The most important file is manifest.ktor.yaml. This defines the essential details of the plugin, including its name, prerequisites, category, and home repository. You can also optionally change the names of some of the other resources. The standard names of the other resources and their purposes are shown below:
group.ktor.yaml | Basic information about the group producing the plugin. |
documentation.md | A description of the plugin, including code snippets for use in the plugin selection screen of the project generator. |
install.kt | The code to be inserted into the generated project if the user selects the current plugin. |
versions.ktor.yaml | A mapping between versions of Ktor and versions of the plugin. In other words, which version of the plugin should be used with which version(s) of Ktor. |
What happens next?
Once you submit your plugin, the Ktor team will try to have it evaluated by the next release. If there are questions or issues, these will be resolved via the usual procedures for managing pull requests on GitHub.
If all is well, the plugin will be added to the generator. Community-based plugins will be differentiated by the inclusion of the contributor’s name, icon, and a link to their website. All contributed code must be licensed with Apache 2.0 and should follow the guidance in the contribution guide.
The Ktor team will keep the project generator up to date as new versions of community plugins are released. Upcoming versions of Ktor will be tested against the appropriate version of each community plugin. If a plugin is no longer compatible with the current version of Ktor, and the issue cannot be resolved, then the plugin will be excluded.
Conclusions
We believe the plugin registry will be of great benefit to the Ktor community. It places community plugins on an equal footing with regular ones and gives the widest possible choice to framework users.
We encourage existing providers to submit their plugins as soon as possible and hope their example will inspire other teams to create and submit their own. For more details please join the discussion on the Ktor channel of Kotlinlang Slack (request an invite to Slack).
Subscribe to Kotlin Blog updates
