Directory Structure

Posted on Aug 03, 2026 by

Projects created via the Cordova CLI come with the following default directory structure:

myapp/
├── config.xml
├── node_modules/
├── package.json
├── platforms/
├── plugins/
└── www

package.json

This manifest file declares JavaScript package dependencies used by the project, including Cordova, added platforms and all installed plugins. Plugin configuration variables are also stored inside this file.

Your project may already have an existing package.json with dependencies (such as those generated by frontend frameworks). Cordova only appends its own required configurations and will not interfere with other tools or existing dependencies.

{
  "name": "com.foxdevelop.hello",
  "displayName": "HelloWorld",
  "version": "1.0.0",
  "description": "A sample Apache Cordova application that responds to the deviceready event.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "ecosystem:cordova"
  ],
  "author": "Apache Cordova Team",
  "license": "Apache-2.0",
  "devDependencies": {
    "cordova-android": "^15.1.0",
    "cordova-plugin-camera": "^8.0.0"
  },
  "cordova": {
    "platforms": [
      "android"
    ],
    "plugins": {
      "cordova-plugin-camera": {
        "ANDROIDX_CORE_VERSION": "1.6.+"
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)
  1. "name": "com.foxdevelop.hello" The npm package name. In Cordova projects, this usually matches the widget id inside config.xml.

Note: This is not the native package name for Android/iOS. The native package identifier is controlled by the id value in config.xml.

  1. "displayName": "HelloWorld" User-friendly display name corresponding to the application name, matching the <name> entry in config.xml.
  2. "version": "1.0.0" Project version number following semantic versioning major.minor.patch. It is recommended to keep this consistent with the version defined in config.xml.
  3. "description": "A sample Apache Cordova application that responds to the deviceready event." Project metadata shown on npm; it does not affect app building or runtime behavior.
  4. "main": "index.js" Standard npm entry point. Cordova rarely uses this field — it is auto-generated by the template and can be ignored. The real web entry point for Cordova apps is www/index.html (controlled via config.xml).
  5. "scripts": { "test": "echo \"Error: no test specified\" && exit 1" } Custom npm scripts. The template only includes a default test command without preconfigured build or packaging shortcuts. You may extend this section later, for example:
"scripts": {
  "build-android": "cordova build android"
}
Code language: JavaScript (javascript)
  1. "keywords": ["ecosystem:cordova"] npm search tag. The ecosystem:cordova label marks the project as part of the Cordova ecosystem; it only affects npm discovery and has no impact at runtime.
  2. "author": "Apache Cordova Team" Author metadata only.
  3. "license": "Apache-2.0" Open-source license: Apache License 2.0, the default license for official Cordova projects.

config.xml

This file stores preferences and configuration options for your Cordova app to customize runtime behavior.

Reference Documentation: Official config.xml Reference

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.foxdevelop.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 that responds to the deviceready event.
    </description>
    <author email="dev@cordova.apache.org" href="https://cordova.apache.org">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />
</widget>
Code language: HTML, XML (xml)

id="com.foxdevelop.hello"Unique application package identifier (Bundle ID)

  • Android: Application package name applicationId
  • iOS: Bundle Identifier

Do not modify this arbitrarily before publishing to app stores! Changing it will be treated as a brand-new application. Standard format: reverse domain notation company.domain.projectname

version="1.0.0" Application version number (semantic version major.minor.patch), applied to the packaged app binary.

<name>HelloWorld</name>

Application display name shown underneath the launcher icon on mobile home screens.

<description>

Application description read by some platforms and app stores during packaging.

<author>

Developer information including email, website and author name; purely metadata with no runtime effect.

<content src="index.html" />

Most critical configuration

The initial page loaded when the Cordova app launches.

Once opened, the application container directly loads www/index.html.

You can change the entry page by setting src="pages/home.html".

<allow-intent>

<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
Code language: HTML, XML (xml)

Purpose: Permit the app to launch external browsers to open web pages

allow-intent ≠ Allowing cross-origin requests inside the web view!

These two settings are often confused:

  1. allow-intent: When clicking links with target="_blank", this controls which URLs can open in the system default browser. The current configuration permits all http/https addresses to trigger an external browser.
  2. access origin: Controls whether the in-app webview can send requests to remote APIs (cross-origin). This entry is missing in the sample above!

⚠️ Common pitfall:

If you encounter cross-origin errors for AJAX API calls inside your web pages, allow-intent alone will not work. You must add the following:

xml

<!-- Allow webview access to all https endpoints -->
<access origin="*" />Code language: HTML, XML (xml)

www/

Stores web assets of your project: HTML, CSS, JavaScript and all static resource files.

As a Cordova developer, most business logic and resources reside here. After running the cordova prepare command, files inside this directory will be copied to the corresponding www folders of each platform.

The source www directory is synced to platform subdirectories. Example paths:

platforms/ios/www or platforms/android/assets/www.

The CLI continuously overwrites platform directory content from the root www folder. Only edit files inside the root www directory; never modify files directly under platforms.

If you use frontend build tools, configure your build output to target the www folder. If you develop source files directly inside www, add this directory to version control.

node_modules/

Holds all JavaScript dependency packages downloaded from npm registry, including Cordova, tooling and dependencies declared in package.json.

When running cordova platform add or cordova plugin add to add platforms or plugins, corresponding resources are fetched from npmjs and downloaded into node_modules/.

Cordova then copies platform and plugin source code from this directory to appropriate locations to guarantee normal application execution.

This directory also contains scripts required for building each platform via cordova prepare and cordova build.

⚠️ Important: node_modules contains raw dependency source files. Do not manually edit any files within it. In addition, do not commit this directory to version control systems.

Consult official npmjs directory specification documentation for extra details.

platforms/

Stores native source code and build scripts for every platform you added to the project.

⚠️ Warning: When building apps through CLI, do not modify any files inside /platforms/ unless you fully understand the internals or official documentation explicitly permits it.

Files under this directory get frequently overwritten during project preparation and plugin reinstallation.

plugins/

Temporary transit directory for plugins. Installed plugins are first copied here before being deployed to individual platform directories.

It is not recommended to commit this directory to version control.

If you develop custom, internal or modified plugins, do not store them inside the plugins folder.

Version Control Guidelines

It is recommended not to track platforms/ and plugins/ with version control because they are build artifacts.

Installed platforms and plugins are automatically recorded within package.json. When executing cordova prepare, required platforms and plugins will be downloaded automatically.

Optional Directory

merges/

The merges directory is not generated by default when creating projects via Cordova CLI. Official documentation discourages its usage but maintains backward compatibility.

Subfolders inside this directory hold platform-specific web assets (HTML, CSS, JS). These resources are deployed into native project folders during the prepare phase.

Files placed inside merges/ override identically named files under www for the corresponding platform.

Example directory layout:

plaintext

myapp/
├── merges
│   ├── android/
│   │   └── android.js
│   └── ios/
│       └── app.js
└── www/
    └── app.js

After compiling Android and iOS builds:

  • Android application: includes app.js (from www) + android.js
  • iOS application: only contains app.js sourced from merges/ios/app.js, overriding the generic app.js inside www

Directory Structure

Posted in Cordova Tutorial

Leave a Reply

Your email address will not be published. Required fields are marked *