Skip to content

How to ‘plugman’ify an existing plugin

In a previous post, I talked about adding a new plugin that you wrote to your Cordova CLI project. However, there are a ton of existing plugins out there, and many of them haven’t yet migrated over to the new plugman architecture. What should you do when there is a plugin that solves your problem, but is not installable via plugman?

Your options include:

  • install the plugin the old fashioned way, by downloading and copying its files into your project directory. This is a a bad idea because if there are future bug fixes or feature improvements to the plugin, you’ll have to manually pull them in.
  • forego the plugin. But you are looking at it specifically to save you time or allow you to implement a feature that would otherwise be too hard or time consuming–so you can’t exactly ignore it.
  • search for another plugin that does the same thing–great, if you can find it.
  • make the plugin plugman compatible–this is the best option.

The first step to making a plugin plugman compatible is to file a bug/issue with the project. Perhaps they are already planning to do this work, and a request from you will get it moved up the queue. If so, fantastic–see when they think it will be done. If not, at least you’ve let them (and others who look at the issues list) know that this is something they should do.

If it won’t be done in your timeframe (or at all), you can do it yourself. The main tassks are writing a plugin.xml file, and possibly modifying some javascript files. Start with the plugin.xml spec.

Before you plunge in, though, think about the licensing surrounding the plugin, as, unless you are replacing everything or the license is extremely permissive, your contributions will need to be under the same or a compatible license as the original code, especially if you want to contribute the changes back.

You want to make sure you use version control. If you are modifying a plugin on github, it is as simple as forking that project. You may be able to take the plugin code and import it into your version control system.

Write the plugin.xml file, and make sure to check it into the version control system. Writing a plugin.xml file is straightforward; however, there are two ways to handle javascript–you can treat it as an asset, where plugman dumbly copies it to the www directory wherever you tell it to, or you can treat it as a js-module. Plugman does some extra work for js-module javascript, including injecting it into the index.html and adding the created javascript object to the window object. Using js-module is the preferred method, but you may have to edit the javascript files and remove any cordova.define syntax. Also, if you need to move plugin files around, or rename them to help code maintainability, do so.

Test and install it just as you would any other plugman managed plugin (cordova plugins add http://...).

Once you’ve done this and it works, consider pointing to your plugin.xml in your open bug. Some authors may be receptive to code contributions or pull requests.

In the next post, I’ll discuss how Cordova CLI helps you release your application.

Subscribe to my infrequent Cordova newsletter