cordova plugin

cordova plugin command

Synopsis

Manage project plugins

Syntax

cordova {plugin | plugins} [
    add <plugin-spec> [..] {--searchpath=<directory> | --noregistry | --link | --save | --browserify | --force | --fetch} |
    {remove | rm} {<pluginid> | <name>} --save --fetch |
    {list | ls} |
    search [<keyword>] |
    save |
]

Sub-command	Option	Description
add `<plugin-spec>` [...]		Add specified plugins
	--searchpath `<directory>`	When looking up plugins by ID, look in this directory and each of its subdirectories before hitting the registry. Multiple search paths can be specified. Use ':' as a separator in `*nix` based systems and ';' for Windows.
	--noregistry	Don't search the registry for plugins.
	--link	When installing from a local path, creates a symbolic link instead of copying files. The extent to which files are linked varies by platform. Useful for plugin development.
	--save	Save the `<plugin-spec>` as part of the `plugin` element into `config.xml`.
	--browserify	Compile plugin JS at build time using browserify instead of runtime.
	--force	Introduced in version 6.1. Forces copying source files from the plugin even if the same file already exists in the target directory.
	--fetch	Fetches the plugin using `npm install` and stores it into the apps `node_modules` directory
remove `	` [...]
	--save	Remove the specified plugin from config.xml
	--fetch	Removes the plugin using `npm uninstall` and removes it from the apps `node_modules` directory
list		List currently installed plugins
search `[<keyword>]` [...]		Search http://plugins.cordova.io for plugins matching the keywords
save		Save `<plugin-spec>` of all plugins currently added to the project

Plugin-spec

There are a number of ways to specify a plugin:

<plugin-spec> : [@scope/]pluginID[@version]|directory|url[#commit-ish][:subdir]

Value	Description
scope	Scope of plugin published as a scoped npm package
plugin	Plugin id (id of plugin in npm registry or in --searchPath)
version	Major.minor.patch version specifier using semver
directory	Directory containing plugin.xml
url	Url to a git repository containing a plugin.xml
commit-ish	Commit/tag/branch reference. If none is specified, 'master' is used
subdir	Sub-directory to find plugin.xml for the specified plugin. (Doesn't work with `--fetch` option)

Algorithm for resolving plugins

When adding a plugin to a project, the CLI will resolve the plugin based on the following criteria (listed in order of precedence):

The plugin-spec given in the command (e.g. cordova plugin add pluginID@version)
The plugin-spec saved in config.xml (i.e. if the plugin was previously added with --save)
As of Cordova version 6.1, the latest plugin version published to npm that the current project can support (only applies to plugins that list their Cordova dependencies in their package.json)
The latest plugin version published to npm

Examples

Add cordova-plugin-camera and cordova-plugin-file to the project and save it to config.xml. Use ../plugins directory to search for the plugins.
```
cordova plugin add cordova-plugin-camera cordova-plugin-file --save --searchpath ../plugins
```
Add cordova-plugin-camera with semver version ^2.0.0 and save it to config.xml:
```
cordova plugin add cordova-plugin-camera@^2.0.0 --save
```
Add cordova-plugin-camera with semver version ^2.0.0 and npm install it. It will be stored in the node_modules directory:
```
cordova plugin add cordova-plugin-camera@^2.0.0 --fetch
```
Clone the specified git repo, checkout to tag 2.1.0, look for plugin.xml in the plugin directory, and add it to the project. Save the plugin-spec to config.xml:
```
cordova plugin add https://github.com/apache/cordova-plugin-camera.git#2.1.0:plugin --save
```
Add the plugin from the specified local directory:
```
cordova plugin add ../cordova-plugin-camera
```

Add the plugin from the specified tarball file:

cordova plugin add ../cordova-plugin-camera.tgz --save

Remove the plugin from the project and the config.xml:
```
cordova plugin rm camera --save
```
Remove the plugin from the project and npm uninstall it. Removes it from the node_modules directory:
```
cordova plugin rm camera --fetch
```
List all plugins installed in the project:
```
cordova plugin ls
```

Conflicting plugins

Conflicting plugins may occur when adding plugins that use edit-config tags in their plugin.xml file. edit-config allows plugins to add or replace attributes of XML elements.

This feature can cause issues with the application if more than one plugin tries to modify the same XML element. Conflict detection has been implemented to prevent plugins from being added so one plugin doesn't try to overwrite another plugin's edit-config changes. An error will be thrown when a conflict in edit-config has been found and the plugin won't be added. The error message will mention that all conflicts must be resolved before the plugin can be added. One option to resolving the edit-config conflict is to make changes to the affected plugins' plugin.xml so that they do not modify the same XML element. The other option is to use the --force flag to force add the plugin. This option should be used with caution as it ignores the conflict detection and will overwrite all conflicts it has with other plugins, thus may leave the other plugins in a bad state.

Refer to the plugin.xml guide for managing edit-config, resolving conflicts, and examples.

Links:

https://cordova.apache.org/docs/en/latest/reference/cordova-cli/index.html#cordova-plugin-command

doc_cordova

2017-01-31 03:40:06

Comments