Cordova - Config.xml File

Cordova - Understanding config.xml

The config.xml file is a mandatory, global configuration file located in the root of your Cordova project. It controls many aspects of your application’s behavior, appearance, and metadata. It’s an XML document based on the W3C Packaged Web Apps (Widgets) specification, with Cordova-specific extensions.

When you create a Cordova project (e.g., using cordova create), a default config.xml file is generated. You will modify this file to customize your app.

Core config.xml Elements

Here’s an overview of essential elements you’ll find and use in config.xml:

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.example.myapp" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>MyAwesomeApp</name>
    <description>
        A sample Apache Cordova application that responds to the deviceready event.
    </description>
    <author email="dev@cordova.apache.org" href="http://cordova.io">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <access origin="*" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />
    <allow-intent href="tel:*" />
    <allow-intent href="sms:*" />
    <allow-intent href="mailto:*" />
    <allow-intent href="geo:*" />

    <platform name="android">
        <allow-intent href="market:*" />
        <!-- Android-specific preferences and configurations -->
        <preference name="ScrollEnabled" value="false" />
    </platform>
    <platform name="ios">
        <allow-intent href="itms:*" />
        <allow-intent href="itms-apps:*" />
        <!-- iOS-specific preferences and configurations -->
        <preference name="BackupWebStorage" value="cloud" />
    </platform>

    <!-- Preferences (global or platform-specific) -->
    <preference name="DisallowOverscroll" value="true" />
    <preference name="Orientation" value="default" />

    <!-- Plugins are typically added here automatically by 'cordova plugin add' -->
    <!-- Example of a manually declared plugin (less common now) -->
    <!-- <plugin name="cordova-plugin-device" spec="~2.0.3" /> -->

    <!-- Icons and Splash Screens -->
    <icon src="res/icon.png" />
    <platform name="android">
        <icon density="ldpi" src="res/android/icon-ldpi.png" />
        <icon density="mdpi" src="res/android/icon-mdpi.png" />
        <!-- ... more densities -->
        <splash density="land-hdpi" src="res/screen/android/splash-land-hdpi.png" />
        <!-- ... more splash screens -->
    </platform>
    <platform name="ios">
        <icon height="57" platform="ios" src="res/ios/icon-57.png" width="57" />
        <!-- ... more icon sizes -->
        <splash height="480" platform="ios" src="res/screen/ios/splash-iphone-portrait.png" width="320" />
        <!-- ... more splash screens -->
    </platform>
</widget>

Key Element Explanations

Element / Attribute	Description & Purpose
<widget>	The root element of the config.xml file. Key attributes:
id	The reverse domain-style identifier for your app (e.g., com.example.myapp). This is crucial for app store submissions.
version	The version number of your app (e.g., 1.0.0). Follow semantic versioning (Major.Minor.Patch).
xmlns	XML namespace for W3C widgets (http://www.w3.org/ns/widgets).
xmlns:cdv	XML namespace for Cordova-specific extensions (http://cordova.apache.org/ns/1.0).
<name>	The application’s display name, as it appears on the device homescreen or in app listings.
<description>	A short description of the application. May be used in app store listings.
<author>	Information about the application author. Attributes: email, href (website).
<content src="..." />	Specifies the app’s starting page (entry point). Typically index.html, located in the www directory.
<access origin="..." />	Controls which network requests (domains) the application is allowed to make. origin="*" allows access to any domain. For better security, restrict this to only the domains your app needs. This works in conjunction with the cordova-plugin-whitelist and CSP meta tags. (Deprecated in favor of allow-navigation for top-level navigation, but still relevant for sub-requests like XHR/Fetch).
<allow-intent href="..." />	Defines which URLs the application is allowed to ask the system to open. For example, tel:* allows launching the dialer, http://*/* and https://*/* allow opening web links in the system browser (not within the app’s WebView).
&lt;allow-navigation href="..." /&gt;	Controls which URLs the WebView itself can navigate to. If not specified, only navigations to file:// URLs are allowed. Use this to allow navigation to remote HTTP/HTTPS sites within your app. E.g., <allow-navigation href="https://*.mycompany.com/*" />.
&lt;platform name="..."&gt; ... &lt;/platform&gt;	Container for platform-specific configurations. Common platforms: android, ios, browser, windows.
&lt;preference name="..." value="..." /&gt;	Sets various options for your app. Preferences can be global (direct children of <widget>) or platform-specific (inside a <platform> block). Examples:
&lt;plugin name="..." spec="..." /&gt;	Declares plugins used by the project. While you primarily use cordova plugin add/rm ... (which updates package.json and config.xml or plugin_list.json), this element shows installed plugins. spec can be a version number, git URL, or local path.
&lt;icon src="..." /&gt; and &lt;splash src="..." /&gt;	Define application icons and splash screens (launch screens). You can specify a default icon/splash, and then platform-specific versions with different sizes, densities, or orientations using attributes like platform, density, width, height.
&lt;edit-config file="..." target="..." mode="..."&gt; ... &lt;/edit-config&gt;	Allows modification of platform-specific configuration files like AndroidManifest.xml (Android) or *-Info.plist (iOS) directly from config.xml. Useful for setting attributes or adding elements not covered by standard preferences.
&lt;resource-file src="..." target="..." /&gt;	Copies files from your Cordova project into the native platform project during prepare. Useful for adding custom resources, sound files, or configuration files to the native build.

Best Practices & Tips

• Version Control: Always keep config.xml under version control (e.g., Git).
• Platform-Specific Settings: Use <platform name="..."> blocks for settings that only apply to one platform.
• Preferences: Consult the Cordova documentation for a full list of available global and platform-specific preferences. Common ones include controlling orientation, fullscreen mode, webview behavior, and more.
• Icons and Splash Screens: Providing icons and splash screens for various resolutions and device types is crucial for a professional app appearance. Tools like cordova-res can help automate their generation.
• Whitelist and CSP: Pay close attention to <access>, <allow-intent>, and <allow-navigation> tags, along with the Content Security Policy (CSP) <meta> tag in your index.html. These are critical for security, controlling what your app can access and what resources it can load.
• Automatic vs. Manual Edits: Cordova CLI commands (like cordova plugin add or cordova platform add) often modify config.xml automatically. Be cautious when manually editing, especially sections managed by the CLI.
• Read the Docs: The official Cordova documentation for config.xml is the definitive source for all elements, attributes, and platform-specific behaviors: Config.xml Reference.

A well-configured config.xml is fundamental to building a robust and polished Cordova application. Take the time to understand its elements and how they affect your app’s build and runtime behavior.