The config.xml File

The config.xml File

Many aspects of an app's behavior can be controlled with a global configuration file, config.xml, that belongs in the top-level web asset directory along with the app's home page. This platform-agnostic XML file is arranged based on the W3C's Packaged Web Apps (Widgets) specification, and extended to specify core Cordova API features, plugins, and platform-specific settings.

For projects created with the Cordova CLI (described in The Command-Line Interface), this file can be found in the top-level www directory:

    app/www/config.xml

When using the CLI to build a project, versions of this file are passively copied along with other web-asset source files into various platforms/*/www subdirectories, for example:

    app/platforms/ios/www/config.xml
    app/platforms/blackberry10/www/config.xml

An exception is Android, whose path specifies an additional assets subdirectory:

    app/platforms/android/assets/www/config.xml

If you use the CLI to create a project, but then shift your workflow to an SDK, you need to use an alternate set of source files for Android and iOS:

    app/platforms/android/res/www/config.xml
    app/platforms/ios/<APP_NAME>/config.xml

This section details global and cross-platform configuration options. See the following sections for platform-specific options:

In addition to the various configuration options detailed below, you can also configure an application's core set of images for each target platform. See Icons and Splash Screens for more information.

Core Configuration Elements

This example shows the default config.xml generated by the CLI's create command, described in The Command-Line Interface:

    <widget id="com.example.hello" version="0.0.1">
        <name>HelloWorld</name>
        <description>
            A sample Apache Cordova application that responds to the deviceready event.
        </description>
        <author email="dev@callback.apache.org" href="http://cordova.io">
            Apache Cordova Team
        </author>
        <content src="index.html" />
        <access origin="*" />
        <preference name="Fullscreen" value="true" />
        <preference name="WebViewBounce" value="true" />
    </widget>

The following configuration elements appear in the top-level config.xml file, and are supported across all supported Cordova platforms:

Global Preferences

The following global preferences apply to all platforms:

Multi-Platform Preferences

The following preferences apply to more than one platform, but not to all of them:

The feature Element

If you use the CLI to build applications, you use the plugin command to enable device APIs. This does not modify the top-level config.xml file, so the <feature> element does not apply to your workflow. If you work directly in an SDK and using the platform-specific config.xml file as source, you use the <feature> tag to enable device-level APIs and external plugins. They typically appear in this form:

    <feature name="Plugin" value="PluginID" />

They often appear with custom values in platform-specific config.xml files. For example, here is how to specify the Device API for Android projects:

    <feature name="Device">
        <param name="android-package" value="org.apache.cordova.device.Device" />
    </feature>

Here is how the element appears for iOS projects:

    <feature name="Device">
        <param name="ios-package" value="CDVDevice" />
    </feature>

See the API Reference for details on how to specify each feature. See the Plugin Development Guide for more information on plugins.