https://github.com/apache/cordova-common
Apache Cordova Common Tooling Library
https://github.com/apache/cordova-common
cordova hacktoberfest javascript mobile nodejs
Last synced: about 2 months ago
JSON representation
Apache Cordova Common Tooling Library
- Host: GitHub
- URL: https://github.com/apache/cordova-common
- Owner: apache
- License: apache-2.0
- Created: 2016-11-28T08:00:08.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2025-02-02T05:05:15.000Z (4 months ago)
- Last Synced: 2025-04-03T04:16:52.509Z (2 months ago)
- Topics: cordova, hacktoberfest, javascript, mobile, nodejs
- Language: JavaScript
- Homepage: https://cordova.apache.org/
- Size: 1.15 MB
- Stars: 41
- Watchers: 18
- Forks: 41
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# cordova-common
[](https://nodei.co/npm/cordova-common/)
[](https://github.com/apache/cordova-common/actions?query=branch%3Amaster)
Exposes shared functionality used by [cordova-lib](https://github.com/apache/cordova-lib/) and Cordova platforms.
## Exposed APIs
### `events`
Represents special instance of NodeJS `EventEmitter` which is intended to be used to post events to `cordova-lib` and `cordova-cli`
Usage:
```js
const { events } = require('cordova-common');
events.emit('warn', 'Some warning message')
```
Here are the following supported events by `cordova-cli`:
* `verbose`
* `log`
* `info`
* `warn`
* `error`
### `CordovaError`
An error class used by Cordova to throw cordova-specific errors. The `CordovaError` class is inherited from `Error`, so it is a valid instance of `Error`. (`instanceof` check succeeds).
Usage:
```js
const { CordovaError } = require('cordova-common');
throw new CordovaError('Some error message', SOME_ERR_CODE);
```
See [CordovaError](src/CordovaError/CordovaError.js) for supported error codes.
### `ConfigParser`
Exposes functionality to deal with cordova project `config.xml` files. For `ConfigParser` API reference check [ConfigParser Readme](src/ConfigParser/README.md).
Usage:
```js
const { ConfigParser } = require('cordova-common');
const appConfig = new ConfigParser('path/to/cordova-app/config.xml');
console.log(`${appconfig.name()}:${appConfig.version()}`);
```
### `PluginInfoProvider` and `PluginInfo`
`PluginInfo` is a wrapper for cordova plugins' `plugin.xml` files. This class may be instantiated directly or via `PluginInfoProvider`. The difference is that `PluginInfoProvider` caches `PluginInfo` instances based on plugin source directory.
Usage:
```js
const { PluginInfo, PluginInfoProvider } = require('cordova-common');
// The following instances are equal
const plugin1 = new PluginInfo('path/to/plugin_directory');
const plugin2 = new PluginInfoProvider().get('path/to/plugin_directory');
console.log(`The plugin ${plugin1.id} has version ${plugin1.version}`)
```
### `ActionStack`
Utility module for dealing with sequential tasks. Provides a set of tasks that are needed to be done and reverts all tasks that are already completed if one of those tasks fail to complete. Used internally by `cordova-lib` and platform's plugin installation routines.
Usage:
```js
const { ActionStack } = require('cordova-common');
const stack = new ActionStack();
const action1 = stack.createAction(task1, [], task1_reverter, []);
const action2 = stack.createAction(task2, [], task2_reverter, []);
stack.push(action1);
stack.push(action2);
stack.process()
.then(() => {
// all actions succeded
})
.catch(error => {
// One of actions failed with error
});
```
### `superspawn`
Module for spawning child processes with some advanced logic.
Usage:
```js
const { superspawn } = require('cordova-common');
superspawn.spawn('adb', ['devices'])
.progress(data => {
if (data.stderr) console.error(`"adb devices" raised an error: ${data.stderr}`);
})
.then(devices => {
// Do something...
});
```
### `xmlHelpers`
A set of utility methods for dealing with XML files.
Usage:
```js
const { xmlHelpers } = require('cordova-common');
const doc1 = xmlHelpers.parseElementtreeSync('some/xml/file');
const doc2 = xmlHelpers.parseElementtreeSync('another/xml/file');
xmlHelpers.mergeXml(doc1, doc2); // doc2 now contains all the nodes from doc1
```
### Other APIs
The APIs listed below are also exposed but are intended to be only used internally by cordova plugin installation routines.
* `PlatformJson`
* `ConfigChanges`
* `ConfigKeeper`
* `ConfigFile`
## Setup
* Clone this repository onto your local machine
```bash
git clone https://github.com/apache/cordova-common.git
```
* Navigate to cordova-common directory, install dependencies and npm-link
```bash
cd cordova-common && npm install && npm link
```
* Navigate to cordova-lib directory and link cordova-common
```bash
cd && npm link cordova-common && npm install
```