Jun 10, 2014

Sharing Cordova projects becomes easier

Whether a project is created using Cordova's CLI or the Eclipse Thym (or JBoss Tools) sharing Cordova projects within a team is unpleasant. Cordova projects include generated artifacts and binary files in their source tree which violates source code management (SCM) best practices.

The first set of generated files are on the {$PROJECT_ROOT}/platforms directory. When using Cordova CLI when a cordova platform add {$PLATFORM} command is issued on a project, a {PROJECT_ROOT}/platforms/{$PLATFORM} directory is generated. This directory contains all your artifacts from {$PROJECT_ROOT}/www, {$PROJECT_ROOT}/merges/{$PLATFORM} directories and all the files necessary to create a native application with the platform build tools. Fortunately, Eclipse Thym generates platform folders on a temporary location and only when needed, hence does not share this problem. When using SCM tools, {$PROJECT_ROOT}/platforms should not be added to source management. For long term sanity, developers should do the extra step when they get the code from SCM and issue  "platform add" commands for the platforms that they will work on.

The {$PLATFORM_ROOT}/plugins folder includes the files for Cordova plugins installed to the project. These files are not usually modified by the developers but installed with the cordova plugin add {$PLUGIN_ID} command. This command creates a {$PLATFORM_ROOT}/plugins/{$PLUGIN_ID} directory and copies the plugin's files in. Eclipse Thym also does a similar thing but it uses a filter on the project explorer so that the files do not confuse developers. Since these files can be regenerated and are not modified during daily development, it is a bad practice to add them to the SCM tools. Because both Cordova CLI and Eclipse Thym did not have a record of installed plugins other than the directories under {$PLATFORM_ROOT}/plugins/ directory, it was not possible to avoid adding them to SCM.

Recently, I have added a couple of new commands to Cordova CLI. cordova save plugins saves the list of currently installed plugins to config.xml. cordova restore plugins reads these entries from config.xml and restores them to the project. The save command also comes with a --shrinkwrap flag to freeze to the installed versions of the plugins. Of course, Eclipse Thym also implements this feature. Here is a demo that shows the feature at work.



With the new save and restore commands and its implementation on Eclipse Thym, it is considerably easier to share Cordova projects but we are not done yet. At this time, restore and save commands support restoring plugins only from Cordova plugin registry but support for more sources should be expected in the future. It is also planned to extend these commands to platforms.

UPDATE: The commands and the functionality has evolved since the original post. Please refer to Cordova platform and plugin version management guide for the latest.