diff --git a/www/docs/en/dev/platform_plugin_versioning_ref/index.md b/www/docs/en/dev/platform_plugin_versioning_ref/index.md index e9c65eeaa7c..7bab969b73e 100644 --- a/www/docs/en/dev/platform_plugin_versioning_ref/index.md +++ b/www/docs/en/dev/platform_plugin_versioning_ref/index.md @@ -24,333 +24,264 @@ description: How to manage platforms & plugins versions. # Version Management -Cordova provides the ability to save and restore platforms and plugins. +Cordova allows developers to **save** and **restore** platforms and plugins, eliminating the need to check in platform and plugin source code. -This feature allows developers to save and restore their app to a known state without having to check in all of the platform and plugin source code. +When a platform or plugin is added, its version details are automatically saved to the `package.json` file. -When adding a platform or plugin, details about the app's platform and plugin versions are automatically saved to the `package.json` file. It is also possible to add a platform or plugin by editing the `package.json` file directly, assuming you know the right tags and syntax. It is not possible to remove plugins or platforms in this manner. The recommended method of adding and removing plugins and platforms is with the Cordova CLI commands `cordova plugin add|remove ...` and `cordova platform add|remove ...` to avoid any out of sync issues. +The recommended way to add or remove platforms and plugins is by using the Cordova CLI commands: -The **restore** step happens automatically when a **`cordova prepare`** is issued, making use of information previously saved in the `package.json` and `config.xml` files. +- `cordova platform add|remove ...` +- `cordova plugin add|remove ...` -One scenario where save/restore capabilities come in handy is in large teams that work on an app, with each team member focusing on a platform or plugin. This feature makes it easier to share the project and reduce the amount of redundant code that is checked in the repository. - -## Platform Versioning - -### Saving Platforms - -To save a platform, issue the following command: - -```bash -cordova platform add ] | directory | git_url> -``` - -After running the above command, the **`package.json`** should update with the platform dependency and cordova related information. - -Example: - -```json -"cordova": { - "platforms": [ - "android" - ] -}, -"dependencies": { - "cordova-android": "^8.0.0", -} -``` - -The `--nosave` flag prevents adding and deleting the specified platform from the `package.json` file. - -Example: - -```bash -cordova platform add ] | directory | git_url> --nosave -``` - -The examples below fetch the package, extract it to `node_modules` and update the `package.json` file accordingly. Under the covers, this process is controlled by the npm CLI. Here are various ways to add platforms. - -*Adding with Cordova resolved name:* - -Example: - -```bash -cordova platform add android -``` +Using these commands helps prevent out-of-sync issues. -The avaialble Cordova resolved names are: - -| Cordova Resolved Name | NPM Package Name | -| --- | --- | -| `android` | `cordova-android` | -| `electron` | `cordova-electron` | -| `ios` | `cordova-ios` | -| `browser` | `cordova-browser` | +While it is technically possible to add a platform or plugin by editing `package.json` directly, this is **strongly discouraged**. -*Adding with Cordova resolved name and pinned version:* - -Example: - -```bash -cordova platform add android@7.1.4 -``` - -This command will explicitly fetch for version `7.1.4`. - -*Adding with npm package name:* - -Example: - -```bash -cordova platform add cordova-android -``` +The restore process runs automatically when executing `cordova prepare`, using the information stored in `package.json` and `config.xml`. This applies to both platforms and plugins. If a platform or plugin is defined in both files, `package.json` takes priority. -*Adding with Git URL:* +One scenario where save/restore capabilities come in handy is in large teams that work on an app, with each team member focusing on a platform or plugin. This feature makes it easier to share the project and reduce the amount of redundant code that is checked in the repository. -Example: +The adding and removing mechanisim that Cordova CLI uses for platforms and plugins is controlled by npm CLI. Below we will take a look at the command syntax and examples. -```bash -cordova platform add https://github.com/apache/cordova-android.git -``` +## Adding Platforms and Plugins -or +**Command Syntax:** ```bash -cordova platform add https://github.com/apache/cordova-android +cordova add [ ...] ``` -or - -```bash -cordova platform add github:apache/cordova-android -``` +The `package-spec` argument supports most formats accepted by the npm CLI. -* **`cordova platform add C:/path/to/android/platform`** +Examples include: - Retrieves the Android platform from the specified directory, adds it to the project, and updates the `package.json` file. +- Scoped and non-scoped npm packages +- Local directory paths +- Git remote URLs +- Tarball archives +- [Cordova Resolved Names](#Cordova-Resolved-Names) for official Cordova platforms -* **`cordova platform add android --nosave`** +Additionally, the `--nosave` flag could be appended to the command to prevent adding of specified platform and plugins from the `package.json` file. - Retrieves the pinned version of `cordova-android` platform from npm, adds it to the project, but does not add it to the `package.json` file. +--- -### Updating or Removing Platforms +**Quick Overview:** -It is possible to update and delete a platform from `config.xml` and `package.json`. +When you add a platform or plugin, `package.json` is updated with its dependencies and Cordova-specific metadata. -To update a platform, execute the following command: +For example, running the following commands in a Cordova project: ```bash -cordova platform update ] | directory | git_url> +cordova platform add android@13.0.0 +cordova plugin add cordova-plugin-device@3.0.0 ``` -To remove a platform, execute one of the following commands: +Would result in `package.json` containing the following entries: -```bash -cordova platform remove -cordova platform rm +```json +"devDependencies": { + "cordova-android": "^13.0.0", + "cordova-plugin-device": "^3.0.0" +}, +"cordova": { + "platforms": [ + "android" + ], + "plugins": { + "cordova-plugin-device": {} + } +} ``` -Some Examples: +When restoring a Cordova project, this metadata determines which platforms and plugins will be installed. -* **`cordova platform update android`** +--- - In addition to updating the `cordova-android` platform to the pinned version, it updates the `package.json` file. +### Various `add` Examples -* **`cordova platform update android@3.8.0`** +- **Cordova Resolved Names for Platforms:** - In addition to updating the `cordova-android` platform to version `3.8.0` it updates the `package.json` file. + ```bash + cordova platform add android + ``` -* **`cordova platform update /path/to/android/platform`** + If no tag or version is specified, the Cordova CLI will fetch the latest release. - In addition to updating the `cordova-android` platform to version found in the provided folder, it updates the `package.json` file. + ```bash + cordova platform add electron@latest + ``` -* **`cordova platform remove android`** + NPM tags are supported and can be appended to the end of the package specification. - Removes the `cordova-android` platform from the project and removes it from the `package.json` file. - - _Note: If the platform definition existed in `config.xml` from a previous version of Cordova CLI, it will also be removed from `config.xml`._ + ```bash + cordova platform add ios@7.1.1 + ``` -* **`cordova platform remove android --nosave`** + Exact release versions published to the npm registry are also supported and can be appended to the end of the package specification. - Removes the `cordova-android` platform from the project, but does not remove it from the `package.json` file. +- **npm Package:** -### Restoring Platforms + ```bash + cordova platform add cordova-android + cordova platform add cordova-android@latest + cordova platform add cordova-android@13.0.0 -Platforms are automatically restored from the `package.json` (and `config.xml`) when executing the **`cordova prepare`** command. + cordova platform add @cordova/some-platform + cordova platform add @cordova/some-platform@latest + cordova platform add @cordova/some-platform@1.0.0 -If a platform is defined in both files, the information defined in `package.json` is used as the source of truth. + cordova plugin some-cordova-plugin + cordova plugin some-cordova-plugin@latest -After `prepare`, any platforms restored from `config.xml` will update the `package.json` file to reflect the values taken from `config.xml`. + cordova plugin add @cordova/some-plugin + cordova plugin add @cordova/some-plugin@latest + cordova plugin add @cordova/some-plugin@1.0.0 + ``` -If you add a platform without specifying a ``, the version that will be installed is taken from `package.json` or `config.xml`. + Scoped and non-scope npm packages are supported for both platforms and plugins. Optionally, npm package tags or released versions can be targeted by appending to the end of the package name. (e.g. `package-name@latest`). -**If discovered** in both files, `package.json` is given higher priority over `config.xml`. + Please note that the scoped packages shown above are only examples and do not exist. -Example: +- **Git remote URL:** -Suppose your `config.xml` file contains the following entry: + ```bash + cordova platform add git://github.com/apache/cordova-android.git + cordova platform add git://github.com/apache/cordova-android.git#feature-branch + cordova platform add git://github.com/apache/cordova-android.git#rel/13.0.0 -```xml - - ... - - ... - -``` + cordova platform add https://github.com/apache/cordova-android.git + cordova platform add https://github.com/apache/cordova-android.git#feature-branch + cordova platform add https://github.com/apache/cordova-android.git#rel/13.0.0 -If you run the command **`cordova platform add android`** with no `` specified, the platform `android@7.1.4` will be retrieved and installed. + cordova platform add https://github.com/apache/cordova-android + cordova platform add https://github.com/apache/cordova-android#feature-branch + cordova platform add https://github.com/apache/cordova-android#rel/13.0.0 + ``` -**Example Order of Priority for Restoring Platforms:** + Various Git URL formats are supported for installing platforms and plugins. Optionally, a treeish (branch name, tag, or commit ID) can be specified by appending `#` to the URL. -Suppose you have defined in `config.xml` and `package.json` a platform and version as follows: + When targeting a treeish, ensure it is production-ready before using it in a production environment. This functionality is useful for testing and reviewing pull requests, future releases, or release votes. -**`config.xml`**: +- **Git service short hand:** -```xml - -``` + ```bash + cordova platform add github:apache/cordova-android + cordova platform add github:apache/cordova-android#feature-branch + cordova platform add github:apache/cordova-android#rel/13.0.0 + ``` -**`package.json`**: + Platforms and plugins can also be checked out from Git repositories using a shorthand format. -```json -"cordova": { - "platforms": [ - "android" - ] -}, -"dependencies": { - "cordova-android": "^8.0.0" -} -``` + If your repository is hosted on another Git service, such as Bitbucket or GitLab, you can modify the command to target these services. -When `prepare` is executed, the version from `package.json` has higher priority over `config.xml` and version `^8.0.0` will be installed. + Branches and tags can also be targeted using the shorthand format. However, ensure that the specified branch or version is production-ready before using it in production. ---- +- **Tarball Archive:** -## Plugin Versioning + ```bash + cordova platform add ~/path/to/a/tarbal.tgz + ``` -The plugin commands are a mirror of the platform commands: + Currently, **only platforms** support installation from a tarball package. The supported archive formats are `.tar.gz`, `.tgz,` and `.tar`. -### Saving Plugins +- **Local Directory Path:** -To save a plugin, you issue the following command: + ```bash + cordova platform add ~/path/to/a/cordova-platform + cordova plugin add ~/path/to/a/cordova-plugin -```bash -cordova plugin add ] | directory | git_url> -``` + cordova platform add C:/Path/to/a/cordova-platform + cordova plugin add C:/Path/to/a/cordova-plugin + ``` -After running the above command, the **`package.json`** should contain something as seen below: + Platforms and plugins can be installed from a local directory path. -```json -"cordova": { - "plugins": { - "cordova-plugin-device": {} - } -}, -"devDependencies": { - "cordova-plugin-device": "^1.0.0" -} -``` +## Removing Platforms and Plugins -The `--nosave` flag prevents adding and deleting specified plugins from `package.json`. To prevent saving a plugin, you issue the following command: +**Command Syntax:** ```bash -cordova plugin add ] | directory | git_url> --nosave +cordova remove ``` -Some Examples: - -* **`cordova plugin add cordova-plugin-device`** - - Retrieves the pinned version of the `cordova-plugin-device` plugin from npm, adds it to the project and updates the `package.json` file. - -* **`cordova plugin add cordova-plugin-device@2.0.1`** - - Retrieves the `cordova-plugin-device` plugin at version `2.0.1` from npm, adds it to the project and updates the `package.json` file. - -* **`cordova plugin add https://github.com/apache/cordova-plugin-device.git`** - - **`cordova plugin add https://github.com/apache/cordova-plugin-device`** - - **`cordova plugin add github:apache/cordova-plugin-device`** +The `remove` command also has an alias of `rm`. - npm retrieves the `cordova-plugin-device` plugin from the git repository, adds it to the project and updates the `package.json`. +The `package-name` argument must be the name of the platform or plugin you want to remove. -* **`cordova plugin add C:/path/to/console/plugin`** +For Apache Cordova's platforms, you **MUST** use the [Cordova Resolved Names](#Cordova-Resolved-Names) when removing them. - Retrieves the `cordova-plugin-device` plugin from the specified directory, adds it to the project, and updates the `package.json` file. +The `--nosave` flag could be appended to the command to prevent removal of specified platform and plugins from the `package.json` file. -### Mass Saving of Plugins on an Existing Project - -If you have a pre-existing project and you want to save all currently added plugins in the project, you can use: - -```bash -cordova plugin save -``` - -### Removing Plugins +--- -It is possible to delete a plugin from `config.xml` and `package.json` with one of the following commands: +### Various `remove` Examples -```bash -cordova plugin remove -cordova plugin rm -``` +- **Removing platforms:** -For Example: + ```bash + cordova platform remove android + ``` -* **`cordova plugin remove cordova-plugin-device`** + The above command will remove the `cordova-android` platform from the project and `package.json` file. - Removes the `cordova-plugin-device` plugin from the project and deletes its entry from `package.json`. + _Note: If the platform definition existed in `config.xml` from older version's of Cordova CLI, it will also be removed from `config.xml`._ - _Note: If the plugin definition existed in `config.xml` from a previous version of Cordova CLI, it will also be removed from `config.xml`._ +- **Removing plugins:** -### Restoring Plugins + ```bash + cordova plugin remove cordova-plugin-device + ``` -Plugins are automatically restored from `package.json` and `config.xml` when executing the **`cordova prepare`** command. + The above command will remove the `cordova-plugin-device` plugin from the project and `package.json` file. -If a plugin is defined in both files, the information defined in `package.json` is used as the source of truth. + _Note: If the plugin definition existed in `config.xml` from older version's of Cordova CLI, it will also be removed from `config.xml`._ -After `prepare`, any plugins restored from `config.xml` will update the `package.json` file to reflect the values taken from `config.xml`. +## Important Notes on Platform Restoration -If you add a plugin without specifying a ``, the version that will be installed is taken from `package.json` or `config.xml`. +1. What version is installed when using `cordova platform add android` and the platform is defined in `config.xml`? -**If discovered** in both files, `package.json` is given higher priority over `config.xml`. + If the `config.xml` file contains the following entry: -Example: + ```xml + + ... + + ... + + ``` -Suppose your `config.xml` file contains the following entry: + When running the **`cordova platform add android`** command with no version provided, it will use the `spec` version defined in `config.xml`. In this example it would be `13.0.0`. -```xml - - ... - - ... - -``` +2. What version is restored if a platform is defined in both `config.xml` and `package.json`? -If you run the command **`cordova plugin add cordova-plugin-device`** with no `` specified, the platform `cordova-plugin-device@2.0.1` will be retrieved and installed. + Suppose your project has the following configurations: -**Example Order of Priority for Restoring Plugins:** + **`config.xml`**: -Suppose you have defined in `config.xml` and `package.json` a plugin and version as follows: + ```xml + + ``` -**`config.xml`**: + **`package.json`**: -```xml - -``` + ```json + "cordova": { + "platforms": [ + "android" + ] + }, + "dependencies": { + "cordova-android": "^13.0.0" + } + ``` -**`package.json`**: + When `cordova prepare` is executed, the version from `package.json` has higher priority over `config.xml`. It will install version `^13.0.0`. -```json -"cordova": { - "plugins": { - "cordova-plugin-splashscreen": {} - } -}, -"devDependencies": { - "cordova-plugin-splashscreen": "1.0.0" -} -``` +## Cordova Resolved Names -When `prepare` is executed, the version from `package.json` has higher priority over `config.xml` and version `1.0.0` will be installed. +| Cordova Resolved Name | NPM Package Name | + | --- | --- | + | `android` | `cordova-android` | + | `electron` | `cordova-electron` | + | `ios` | `cordova-ios` | + | `browser` | `cordova-browser` |