This is an automated email from the ASF dual-hosted git repository.
GitToTheHub pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 862bc393e6 docs: document Cordova package.json fields (#1520)
862bc393e6 is described below
commit 862bc393e6361a6341dff373e397851844b03151
Author: Ifeanyi Chima <[email protected]>
AuthorDate: Wed Sep 23 13:26:39 2026 +0100
docs: document Cordova package.json fields (#1520)
- Added a new package.json API reference page documenting: name,
displayName, and version, cordova.platforms, cordova.plugins, devDependencies
- When and how the Cordova CLI updates these fields
- The effect of the --nosave option
- Also added the new reference page to the documentation table of contents.
- Fixes #1005
---
www/_data/toc/en_latest-src.yml | 1 +
www/docs/en/latest/package_ref/index.md | 152 ++++++++++++++++++++++++++++++++
2 files changed, 153 insertions(+)
diff --git a/www/_data/toc/en_latest-src.yml b/www/_data/toc/en_latest-src.yml
index 6e81cb676d..352ea7d15e 100644
--- a/www/_data/toc/en_latest-src.yml
+++ b/www/_data/toc/en_latest-src.yml
@@ -52,6 +52,7 @@
name: References
children:
- url: config_ref/index.html
+ - url: package_ref/index.html
- url: plugin_ref/spec.html
- url: cordova/events/events.html
diff --git a/www/docs/en/latest/package_ref/index.md
b/www/docs/en/latest/package_ref/index.md
new file mode 100644
index 0000000000..466524931a
--- /dev/null
+++ b/www/docs/en/latest/package_ref/index.md
@@ -0,0 +1,152 @@
+---
+license: >
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+title: package.json API
+description: List of Cordova-specific fields in the package.json file, and
when the CLI updates them.
+---
+
+{% cdv_platform inject %}
+
+# package.json API
+
+Alongside `config.xml`, every Cordova project created with the CLI also has a
standard npm
[`package.json`](https://docs.npmjs.com/cli/configuring-npm/package-json) file.
Cordova reads and writes fields inside `package.json` to keep track of your
project's platforms and plugins.
+
+This page lists the Cordova-specific fields you may find in your
`package.json`, and explains when and how the CLI updates each one, so that you
know what's safe to edit by hand and what's managed for you.
+
+**Sample `package.json`:**
+
+```json
+{
+ "name": "io.cordova.hellocordova",
+ "displayName": "HelloCordova",
+ "version": "1.0.0",
+ "description": "Sample Apache Cordova App",
+ "main": "index.js",
+ "scripts": {
+ "test": "echo \"Error: no test specified\" && exit 1"
+ },
+ "cordova": {
+ "platforms": [
+ "android",
+ "ios"
+ ],
+ "plugins": {
+ "cordova-plugin-device": {}
+ }
+ },
+ "devDependencies": {
+ "cordova-android": "^13.0.0",
+ "cordova-ios": "^7.0.0",
+ "cordova-plugin-device": "^2.1.0"
+ }
+}
+```
+
+## name, displayName, version
+
+Set automatically when a project is first created with `cordova create`,
alongside `config.xml`. Cordova does not go back and update these values later
if `config.xml` changes.
+
+Field | Description
+----------------- | ------------
+name | Copied from `config.xml`'s `widget id` attribute (the app's reverse-DNS
identifier), converted to lowercase.
+displayName | Copied from `config.xml`'s `<name>` element (the app's
human-readable name).
+version | Copied from `config.xml`'s `widget version` attribute.
+
+Examples:
+
+```json
+{
+ "name": "io.cordova.hellocordova",
+ "displayName": "HelloCordova",
+ "version": "1.0.0"
+}
+```
+
+## cordova.platforms
+
+An array listing the platforms currently installed in the project. Entries are
added automatically when you run `cordova platform add <platform>`, and removed
when you run `cordova platform remove <platform>`. Adding a platform that's
already listed will not create a duplicate entry.
+
+Automatic saving can be turned off with the [`--nosave`
flag](#cli---nosave-flag).
+
+Examples:
+
+```json
+{
+ "cordova": {
+ "platforms": ["android", "ios"]
+ }
+}
+```
+
+```bash
+cordova platform add android
+cordova platform add ios --nosave
+```
+
+## cordova.plugins
+
+An object listing the plugins currently installed in the project. Each key is
a plugin's ID, and its value holds any CLI variables that were supplied when
the plugin was installed (or an empty object if none were needed). Entries are
added by `cordova plugin add <plugin>` and removed by `cordova plugin remove
<plugin>`. Automatic saving can be turned off with the [`--nosave`
flag](#cli---nosave-flag).
+
+Examples:
+
+```json
+{
+ "cordova": {
+ "plugins": {
+ "cordova-plugin-camera": {},
+ "cordova-plugin-some-plugin": {
+ "API_KEY": "my-api-key"
+ }
+ }
+ }
+}
+```
+
+```bash
+cordova plugin add cordova-plugin-camera
+cordova plugin add cordova-plugin-some-plugin --variable API_KEY=my-api-key
+```
+
+## devDependencies
+
+A standard npm field, not unique to Cordova. See npm's docs on
[`devDependencies`](https://docs.npmjs.com/cli/v12/configuring-npm/package-json#devdependencies)
for the general behavior. When a platform or plugin is installed, Cordova's
tooling also records it here as an npm dependency, alongside its installed
version number. This is separate from [`cordova.platforms`](#cordovaplatforms)
and [`cordova.plugins`](#cordovaplugins), `devDependencies` tracks the actual
npm package and version [...]
+
+Automatic saving can be turned off with the [`--nosave`
flag](#cli---nosave-flag).
+
+Examples:
+
+```json
+{
+ "devDependencies": {
+ "cordova-android": "^13.0.0",
+ "cordova-plugin-camera": "^7.0.0"
+ }
+}
+```
+
+## CLI --nosave Flag
+
+By default, `cordova platform add` and `cordova plugin add` automatically save
what you installed into `package.json`. If you'd rather install something
without permanently adding it to your project's configuration, for example, to
test a plugin temporarily, pass the `--nosave` flag:
+
+```bash
+cordova platform add android --nosave
+cordova plugin add cordova-plugin-camera --nosave
+```
+
+This applies to `cordova.platforms`, `cordova.plugins`, and `devDependencies`
all at once, there's a single flag, not one per field.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
