How I develop or fix Cordova plugins

I spent most of my development career working with Cordova apps so far. If you are reading this, you probably already use Cordova, but just a few words about what it is. Cordova is a tool that helps you develop mobile apps with web technologies like HTML, CSS and JavaScript. Cordova takes care of creating the native app bundles you can upload to the app stores and helps you access device APIs like fingerprint readers via plugins.

Cordova is an Apache project and almost everything around Cordova is open source. The project has some “core plugins” managed by Apache, but many plugins come from the community. Many individuals and companies release their plugins on GitHub and NPM.

From Cordova app developer..

If you want to develop an app with a few native features Cordova might help you get started quickly. If you heavily depend on performance or OS integration, a native app might suit you better. Choose wisely, as Cordova apps with many plugins and workarounds for webview quirks can be a pain. I speak from experience.

With Cordova you create and build the app from the CLI. You then need to identify good plugins for your needs and install them. Then you can create the user interface of your app with HTML, CSS and JavaScript and use the native features provided by plugins with JavaScript.

If your app grows, you want more features or integrations or you get in trouble with plugins for some reason. You become a plugin developer suddenly.

… to Cordova plugin developer

Cordova plugin development is not as hard as you might think. You don’t need to be a native developer or even have experience with the programming languages (Java, Kotlin, Objective-C, Swift). I work in iOS and Android plugins all the time without any proper Objective-C or Swift experience. Just try it step by step.

If you know a little bit how Cordova is designed the plugin development workflow get’s significantly less painful. You might already know that Cordova treats the platforms folder as a build asset and plugins as external dependencies. Therefore they should not be checked into your version control system (you defintely should have one and use it). This means if you change plugins or platforms your changes get lost easily.

I found some workflows that work good for me.

Creating or changing plugins

I think many developers will find themselves in the position where the want to use a plugin but it’s working not quite right and they need to fix something. Sometimes you might want to create your own plugin. The process is very similar. When I create a new plugin I usually just copy a simple plugin and change all names and delete the stuff I don’t need. Then I start adding the features with the same approach I use for exisiting plugins.

Using a app project with the wrong Git setup

When I develop plugins I usually create a new Cordova app project from scratch. Then I just add the parts I need for that plugin. I find this a bit easier than working with a big project with many plugins. Then I set up Git exactly how Cordova tells us not do. I remove the platforms and plugins directory from .gitignore. Then I add the plugin and platform and commit everything to Git. This way I know exactly what I or Cordova changed in the project which becomes useful later.

With everything tracked and commited to Git I have a clean state for starting to develop the plugin.

Of course I do this just for these test apps for developing plugins. My productions apps have a proper Git setup and all plugins are installed from NPM or GitHub. They might use forked plugins. A few words about that later in this post.

Working in the platform

Now we can go into the “forbidden places” of Cordova projects and change stuff there. Git will tell us what we did and we can copy it once it’s ready. I usually write the native for Cordova plugins in either Xcode or Android Studio because it’s a lot easier to write native code in its natural habitat. Now you develop native features for your plugins, debug and test it just if it would be a “normal app”.

Cordovas plugin system is not as magically as you might think. It just calls native functions in plugin classes from JavaScript. You write the native functions with the device APIs as you need, make sure that you have the JavaScript bridge code and you are done.

If you are working on a plugin that uses hooks Git is also helpfull to see what your hooks changed in the project and to revert changes. Hooks are JavaScript scripts that can get executed at certain stages of Cordova CLI commands.

If your plugin now works as expected when you launch the app from the native IDE the hard part is done. I use Git to commit changes to the native projects during and after developing and testing in this app project to make sure my code does not get lost. We will move it to the plugin later.

Securing you work

Because we did our development in “forbidden places” we need to back up our code before it’s gone. As we discussed before removing the platform or plugin deletes the code in the “forbidden places”. Cordova might change code if you build, too. That’s why Git is good to keep track of everything.

Now let’s back up the code. We did everything in our test app but we need it in the plugin. You might already have the plugins repo somewhere so it’s usually just a matter of copy and pasting all files from the platforms directory into your plugin repository. You can copy just your changes if you remember them (Git helps a lot there) or the complete files. Be careful what you copy and always check your changes in the plugin project. JavaScript for example might be different because Cordova bundles it. Only copy what it is really part of your change.

A little example: We want to work on the plugin cordova-plugin-my-plugin and create a test app directory my-plugin-dev. Then we develop the changes in my-plugin-dev/platforms/ios or my-plugin-dev/platforms/android and copy it to cordova-plugin-my-plugin outside the my-plugin-dev diretory.

Then we can commit the changes in our plugin repo, push them to GitHub and release the plugin on NPM. I might write about how I publish plugins, too. Now the code is safely where it belongs and we can install the plugin from NPM or the GitHub URL with cordova plugin add in our real production project.

Plugin forks & pull requests

If you fixed something in a plugin you should create a pull request for the project. If your fix get’s merged and released you can just update the plugin in your project. This is the best case to have your project updated and tidy. But it might take a while for your fix to get released. The project might be abandoned or your fix is something the project doesn’t want to merge. Then you need to use a fork in your app. I recommend that you fork the project on GitHub into your personal or organization account and push your changes to a different branch than the default branch. I always create a new branch for each feature or fix. Then I maintain a branch often called custom with all my branches merged in. If the upstream project changes I rebase my branch to get the latest version + my changes. You can add your fork to your app with cordova plugin add https://GitHub/<name>/<plugin-name>#<branch-name>. To update your branch you need to uninstall the plugin and then install it again.

Working with Git, rebasing and keeping your branches tidy is not easy but you will figure it out with some practice and I think it’s way better and easier than patching plugins manually all the time and having a huge chaos.

Closing thoughts

Cordovas design choices might make plugin development more complicated than it needs to be but with a basic understanding how it works it’s not that hard. I hope my tips and workflows can help you a bit with the next plugin issue.

The Cordova plugin ecosystem is very big but sometimes a little outdated. With a bit of work you might get the plugin you need working even it’s not maintained very well. Creating pull requests and maintaining forks can help other developers.