lempere/cordova-check-plugins

A CLI tool to check for / manage plugin updates in Cordova/Phonegap projects.

cordova-check-plugins

A CLI tool to check for / manage plugin updates in Cordova/Phonegap projects.

Table of Contents

• Purpose
  • Use cases
• Installation
• Usage
  • Command-line options
    • -h or --help
    • -v or --version
    • --verbose
    • --update={mode|pluginIds}
    • --unconstrain-versions
    • --force, --force-update
    • --nosave
    • --github-username and --github-password
    • --target
    • --allow-downdate
    • --remove-all
    • --obfuscate-credentials
    • --nofetch
    • --cwd
    • --nospinner
• Supported plugin sources
• Integration with Cordova CLI
• License

Purpose

This tool intends to provide a convenient way to check if the plugins contained within a Cordova project are up-to-date and to optionally update them.

It has arisen from my own necessity when managing complex Cordova projects containing many plugins.

I dedicate a considerable amount of my free time to developing and maintaining this tool, along with my other Open Source software. To help ensure this tool is kept updated, new features are added and bugfixes are implemented quickly, please donate a couple of dollars (or a little more if you can stretch) as this will help me to afford to dedicate time to its maintenance. Please consider donating if you're using this tool in an app that makes you money, if you're being paid to make the app, if you're asking for new features or priority bug fixes.

Use cases

This tool is useful for:

• Checking if updates are available for plugins installed in a project.
• Updating outdated plugins, either automatically or interactively.
• Keeping installed plugin versions in sync with those specified in config.xml
• Quickly removing all installed plugins in a project.

Installation

npm install -g cordova-check-plugins

Usage

Once cordova-check-plugins is installed globally, it can be run from the root of any Cordova/Phonegap project:

$ cordova-check-plugins

By default, it will display lists of plugins under the following categories:

• "Plugin update available" - installed plugins for which a new remote version is available (displayed in green)
• "Installed plugin version newer than remote default" - installed plugins for which the installed version is newer than the default remote version (displayed in yellow)
• "Unknown plugin version mismatch" - installed plugins for which the remote version could not be determined as older/newer (displayed in yellow)
• "Error checking plugin version" - installed plugins for which an error occurred while checking the plugin versions (displayed in red)
• "Up-to-date plugins" - installed plugins which are up-to-date with the detected remote version (displayed in grey)

Plugins for which updates are available can optionally be updated either interactively or automatically via the --update command-line option.

Command-line options

-h or --help

$ cordova-check-plugins -h
$ cordova-check-plugins --help

Displays usage information.

-v or --version

$ cordova-check-plugins -v
$ cordova-check-plugins --version

Displays currently installed version of this module.

--verbose

Displays detailed log output.

$ cordova-check-plugins --verbose

--update={mode|pluginIds}

Specifies update mode for plugins which have updates available. Valid modes are:

• none - (default) don't update plugins
• interactive - using interactive CLI to choose which plugins to update manually
• auto - automatically update any plugins for which an update is available

i.e.

$ cordova-check-plugins --update=none
    same as:  $ cordova-check-plugins
$ cordova-check-plugins --update=interactive
$ cordova-check-plugins --update=auto

Or where pluginIds is the ID of a single specific plugin to update, or a space-separated list of multiple plugin IDs.

e.g

$ cordova-check-plugins --update=cordova-plugin-geolocation
$ cordova-check-plugins --update="cordova-plugin-geolocation cordova-plugin-dialogs"

--unconstrain-versions

$ cordova-check-plugins --unconstrain-versions

Unconstrains checking of remote version so the highest remote version will be displayed regardless of specified version.

By default, if the version was specified when the plugin was installed, the specified version number will be used to constrain which remote versions are returned.

For example, let's say cordova-plugin-foo has remote versions 1.0.1, 1.0.2, 1.1.0, 2.0.0:

• If cordova plugin add cordova-plugin-foo was used to install the plugin, then cordova-check-plugins will return the highest remote version as 2.0.0
• If cordova plugin add cordova-plugin-foo@1 was used to install the plugin, then cordova-check-plugins will return the highest remote version as 1.1.0
• If cordova plugin add cordova-plugin-foo@1.0 was used to install the plugin, then cordova-check-plugins will return the highest remote version as 1.0.2
• If cordova plugin add cordova-plugin-foo@1.0.1 was used to install the plugin, then cordova-check-plugins will return the highest remote version as 1.0.1
• If cordova plugin add cordova-plugin-foo@~1.0.1 was used to install the plugin, then cordova-check-plugins will return the highest remote version as 1.0.2
• If cordova plugin add cordova-plugin-foo@^1.0.1 was used to install the plugin, then cordova-check-plugins will return the highest remote version as 1.1.0

Calling cordova-check-plugins --unconstrain-versions will ignore the specified version, so in the example above, all cases would return 2.0.0.

Note that this only option affects plugins whose source is npm. It will have no effect on plugins installed directly from github repos. This is because it's not possible to distinguish if github URLs contain a branch or a tag reference. Both are specified using #. So it's not possible to distinguish a tag URL (e.g. http://github.com/some/repo#r1.2.3) from a branch URL (e.g. http://github.com/some/repo#some_branch).

--force, --force-update

Forces the update of dependent plugins when updating plugins. By default, Cordova/Phonegap will not allow the removal of plugins on which other plugins are dependent, and therefore will not allow them to be updated/removed. For example, cordova-plugin-file-transfer depends on cordova-plugin-file. By setting this option, both plugins will be updated (if updates are available). Without it, only the "parent" plugin - in this case cordova-plugin-file-transfer - will be updated.

$ cordova-check-plugins --update=auto --force

--nosave

Omits saving changes when updating plugins. By default (if this argument is omitted), when updating plugins, changes will be saved to config.xml and package.json.

$ cordova-check-plugins --update=auto --force-update --nosave
$ cordova-check-plugins --remove-all --nosave

--github-username and --github-password

Allows specification of user credentials for GitHub, increasing API request limit to 5000 requests/hour. Also enables access to private repos.

When checking remote versions for that are hosted on GitHub, by default unauthenticated access to the GitHub API is used. This is rate limited to 60 requests/hour. For most users, this should be sufficient, but if this module is used in a Continuous Integration environment with a project using multiple GitHub-hosted plugins, that rate can be exceeded. By specifying valid GitHub user credentials, these will be used when communicating with the GitHub API, which increases the number of allowed requests to 5000 requests/hour.

$ cordova-check-plugins --github-username=myUsername --github-password=myPassword

--target

Sets the target to use for establishing if installed plugins are up-to-date.

Valid values are:

• remote - (default) installed plugin versions will be compared to available versions in the remote source (e.g npm registry, git repo, local folder).

• config - installed plugin versions will be to compared to the versions specified in <plugin> elements in the config.xml file.

  $ cordova-check-plugins --target=config

Setting --target=config is useful if you want to keep locally installed plugins in sync with the versions specified in the config.xml, rather than the newest remote versions.

--allow-downdate

If the installed plugin version is newer than the version specified in the config.xml, allow the plugin to be downgraded to the version specified in the config.xml. Only applies if --target=config.

$ cordova-check-plugins --target=config --allow-downdate

--remove-all

$ cordova-check-plugins --remove-all

Removes all installed plugins from the project. If --save is also specified, entries will also be removed from config.xml. This option is exclusive and the default behaviour of checking for plugin updates will be skipped, as will any updates if --update is specified.

--obfuscate-credentials

$ cordova-check-plugins --obfuscate-credentials="my_password my_access_token"

A space-separated list of credentials to obfuscate when logging output to the console. This is useful if your plugin source URLs contain sensitive credentials such as passwords or access tokens that you don't want to appear in console output from the tool. Any credentials specified here will be replaced with {obfuscated} in the console output.

--nofetch

$ cordova-check-plugins --update=auto --nofetch

If using cordova@7+, forces Cordova CLI to use legacy git clone mechanism when installing plugins, rather than the default npm install method. Only applies when updating plugins. See the Cordova 7 release notes for more details.

--cwd

$ cordova-check-plugins --cwd=/path/to/project

Sets the directory from which the tool should be executed. If not specified, defaults to the directory from which the cordova-check-plugins command is executed.

--nospinner

$ cordova-check-plugins --nospinner

Turns off the CLI spinner which is used by default to indicate when an async operation is in progress.

If you're capturing the output of this command to a log (e.g. in a CI environment), then this spinner pollutes the log with unnecessary junk, so turning it off makes for a more readable log.

Supported plugin sources

• Plugins installed via the npm registry (with optionally specified versions)
• Plugins installed directly from GitHub repos (with optionally specified branches/tags)
• Plugins installed from local sources (on the local machine)

For example:

cordova-plugin-camera
cordova-plugin-geolocation@*
cordova-plugin-whitelist@1
cordova-plugin-file@4.0.0
cordova-plugin-inappbrowser@~1.1.1
cordova-plugin-device@^1.0.0
https://github.com/apache/cordova-plugin-battery-status
cordova-plugin-battery-status@https://github.com/apache/cordova-plugin-battery-status   <-- cordova@7 syntax 
https://github.com/apache/cordova-plugin-battery-status#r1.0.0
git://github.com/apache/cordova-plugin-battery-status.git#r1.0.0
https://username:password@github.com/apache/cordova-plugin-battery-status
https://access_token:@github.com/apache/cordova-plugin-battery-status
/some/local/path/to/a/plugin

Integration with Cordova CLI

Using cordova-plugin-config-command, this tool can be triggered during the Cordova CLI build cycle by inserting a <command> into the config.xml.

For example, to automatically update installed plugins to match versions specified in the config.xml:

<command
    name="cordova-check-plugins"
    args="--target=config --update=auto --allow-downdate"
    hook="before_prepare"
    display_output="true"
    abort_on_error="true"
/>

License

The MIT License

Copyright (c) 2015 Dave Alden / Working Edge Ltd.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.