config.xml Deep Dive

config.xml is the single manifest that describes your Cordova app to every platform it builds for — its identity, its display name, its starting page, behavioral preferences, which plugins it depends on, and platform-specific overrides. Every setting you configure here flows into the generated native project the next time you run cordova build or cordova prepare. This page walks through a complete, realistic example element by element.

A Complete Worked Example

<?xml version="1.0" encoding="UTF-8"?>
<widget id="com.example.hello" version="1.0.0"
        xmlns="http://www.w3.org/ns/widgets"
        xmlns:cdv="http://cordova.apache.org/ns/1.0">

    <name>HelloWorld</name>
    <description>
        A sample Apache Cordova application.
    </description>
    <author email="you@example.com" href="https://example.com">
        Sonu Kumar Pandit
    </author>

    <!-- The app's entry point -->
    <content src="index.html" />

    <!-- Behavioral preferences -->
    <preference name="Orientation" value="portrait" />
    <preference name="Fullscreen" value="false" />
    <preference name="BackgroundColor" value="0xff0000ff" />

    <!-- Plugins the CLI has installed for this project -->
    <plugin name="cordova-plugin-camera" spec="^7.0.0" />
    <plugin name="cordova-plugin-geolocation" spec="^5.0.0" />

    <!-- Platform-specific overrides -->
    <platform name="android">
        <icon src="res/icon/android/icon.png" />
        <preference name="AndroidLaunchMode" value="singleTop" />
    </platform>

    <platform name="ios">
        <icon src="res/icon/ios/icon.png" />
        <splash src="res/screen/ios/splash.png" />
    </platform>

</widget>

The `<widget>` Root Element

Every setting in the file lives inside a single root <widget> element, which itself carries two of the most important attributes in the whole file:

Attribute	Meaning
id	The app's reverse-domain identifier (e.g. com.example.hello) — the same value you passed to cordova create. This uniquely identifies your app to the OS and to app stores; changing it after publishing effectively creates a brand-new app listing.
version	A semantic version string (MAJOR.MINOR.PATCH, e.g. 1.0.0) representing your app's release version.

`<name>`, `<description>`, and `<author>`

These three elements are straightforward metadata: <name> is the display name shown under the app icon, <description> is a short summary that can surface in app store listings, and <author> records who built the app along with optional contact details.

`<content>` — the App's Entry Point

<content src="index.html" /> tells Cordova which file inside www/ the native WebView should load first when the app launches. Unless you have an unusual reason to rename your entry file, this stays as index.html.

`<preference>` — Platform Behavior Toggles

<preference> elements are simple name/value switches that control how the native shell behaves, without requiring any native code. Common examples include locking Orientation to portrait or landscape, toggling Fullscreen mode (hides the status bar), or setting a BackgroundColor shown before your web content paints. Preferences placed at the top level apply to every platform; preferences placed inside a <platform> block apply only to that one.

`<plugin>` Entries

Whenever you run cordova plugin add <plugin-name>, the CLI automatically adds a matching <plugin name="..." spec="..." /> entry to config.xml (and removes it on cordova plugin remove) — you rarely type these by hand. Their value is that config.xml becomes a complete, portable record of every native dependency your app needs: cloning the project and running cordova prepare reinstalls every listed plugin automatically.

`<platform>` Blocks

A <platform name="android"> or <platform name="ios"> block lets you nest elements that should only apply to that specific target — most commonly custom app icons and splash screens at various required resolutions, but also platform-only preferences like AndroidLaunchMode.

Why Bumping `version` Matters

Every time you submit an update to the Google Play Store or Apple App Store, the store requires a version (and, on Android, a separate internal android-versionCode integer) higher than the previously published one — otherwise the store rejects the upload outright. Forgetting to bump version in config.xml before a release build is one of the most common, entirely avoidable submission failures, so it's worth building the habit of bumping it as part of your release checklist every single time.