Cordova - Plugman

Cordova - Plugman Command-Line Tool

Plugman is a command-line tool for installing and managing Cordova plugins, primarily on a per-platform basis. While most app developers will use the Cordova CLI (cordova plugin add/remove ...) which handles plugins across all project platforms, Plugman can be useful for plugin developers or for more granular control over plugins within a specific platform’s native project.

When to Use Plugman vs. Cordova CLI

• Cordova CLI (cordova plugin ...): This is the recommended way for app developers to manage plugins. It works at the Cordova project level, automatically handling plugin installation/uninstallation for all added platforms and updating necessary configuration files (like config.xml and package.json).
• Plugman: More suitable for:
• • Plugin Developers: For testing and managing their plugins during development.
• • Specific Platform Modification: If you need to install a plugin only for one platform in an existing Cordova project, or if you are working directly within a platform’s native project structure (e.g., an Android Studio project generated by Cordova).
• • Automated Scripts: For custom build or integration scripts that require fine-grained plugin management.

In general, if you’re building a cross-platform Cordova app, stick to the Cordova CLI for plugin management to ensure consistency.

Step 1 - Installing Plugman

Plugman is a Node.js package and can be installed globally using npm (Node Package Manager). Open your terminal or command prompt:

npm install -g plugman

Verify the installation:

plugman -v

Step 2 - Using Plugman to Install Plugins

To install a plugin using Plugman, you need to specify the platform, the path to the platform’s project, and the plugin to install (either by name from npm, by URL to a git repository, or by path to a local plugin directory).

Syntax:

plugman install --platform <platform> --project <project_path> --plugin <plugin_id_or_path>

Parameters:

• --platform: The target platform (e.g., android, ios, browser).
• --project: The path to the root directory of the native platform project (e.g., ./platforms/android or ./platforms/ios within a Cordova project).
• --plugin: The plugin identifier (e.g., cordova-plugin-device from npm), a Git URL, or a local path to the plugin’s directory.

Example: Installing the Device Plugin for Android

Assuming you have a Cordova project with the Android platform added, navigate to your Cordova project’s root directory and run:

# Ensure you are in your Cordova project's root directory
# Example: MyCordovaApp/

plugman install --platform android --project ./platforms/android --plugin cordova-plugin-device

If successful, Plugman will add the plugin’s native code to the Android project and update relevant configuration files within the platforms/android directory.

Step 3 - Using Plugman to Uninstall Plugins

Similarly, you can uninstall plugins on a per-platform basis.

Syntax:

plugman uninstall --platform <platform> --project <project_path> --plugin <plugin_id>

Example: Uninstalling the Device Plugin for Android

# Ensure you are in your Cordova project's root directory

plugman uninstall --platform android --project ./platforms/android --plugin cordova-plugin-device

Other Plugman Commands

Plugman offers several other commands for plugin management and development:

Command	Description
plugman fetch --plugin <plugin_id_or_path> --destination <path>	Fetches a plugin’s source code and copies it to a specified local directory.
plugman create --name <PluginName> --plugin_id <plugin-id> --plugin_version <version> [--path <path>]	Helps scaffold a new Cordova plugin structure.
plugman platform add --platform_name <platform>	(Used within a plugin directory) Adds platform-specific code support to a plugin project.
plugman platform remove --platform_name <platform>	(Used within a plugin directory) Removes platform-specific code support from a plugin project.
plugman createpackagejson <plugin_path>	Generates a package.json file for an existing plugin from its plugin.xml.
plugman search <keyword1> [keyword2...]	Searches the plugin registry (npm by default) for plugins matching keywords.
plugman publish <plugin_path>	Publishes a plugin in the given path to the plugin registry (npm).
plugman unpublish [--force] <plugin_id>[@<version>]	Unpublishes a plugin version from the registry.
plugman owner add <user> <plugin_id> / plugman owner rm <user> <plugin_id> / plugman owner ls <plugin_id>	Manage plugin ownership on the registry.
plugman adduser / plugman login	Authenticates with the plugin registry.
plugman config set <key> <value> / plugman config get <key> / plugman config delete <key>	Manages Plugman configuration, like the registry URL.
plugman help [command] or plugman -h [command]	Displays help information for Plugman or a specific command.

Important Considerations

• Project Synchronization: If you use Plugman to modify plugins within a platform directory (e.g., platforms/android), these changes might not be reflected in your main Cordova project’s config.xml or package.json. This can lead to inconsistencies if you later run cordova prepare or cordova platform rm/add, as Cordova CLI relies on these top-level configurations. It’s generally safer to let the Cordova CLI manage the platforms directory.
• Plugin Dependencies: Plugman itself may not automatically handle complex plugin dependencies in the same way cordova plugin add does (which resolves them using npm).
• Use Cases: Plugman’s strength lies in its role as a lower-level tool. For plugin authors, it’s invaluable for creating, testing, and publishing plugins. For app developers, Cordova CLI is usually the more straightforward and safer choice for managing plugins in their projects.

For most Cordova application development, relying on cordova plugin add <plugin_name> and cordova plugin rm <plugin_name> is the recommended approach for ease of use and project consistency across multiple platforms.