Project Structure

Previous Next

When cordova create scaffolds a new project, it generates a specific folder layout, and knowing what belongs where — and, just as importantly, what you should never touch by hand — will save you from a lot of confusing, hard-to-debug mistakes later. This page breaks down every top-level item Cordova generates.

The Full Directory Tree

A typical freshly-created project (after adding the android platform) looks like this:

hello/
├── config.xml
├── hooks/
│   └── README.md
├── merges/
│   ├── android/
│   ├── browser/
│   └── ios/
├── platforms/
│   └── android/
│       └── ... (generated native Android Studio project)
├── plugins/
│   ├── fetch.json
│   └── android.json
├── res/
│   ├── icon/
│   └── screen/
└── www/
    ├── css/
    │   └── index.css
    ├── img/
    │   └── logo.png
    ├── js/
    │   └── index.js
    └── index.html

Reference: What Every Item Is For

Path	Purpose
`www/`	Your actual web app source — HTML, CSS, and JavaScript. This is the only folder you should be editing day to day; every screen, style, and line of app logic you write goes here.
`platforms/`	Fully generated native project code for each platform you've added (a real Android Studio / Gradle project for `android`, an Xcode project for `ios`, etc). Cordova regenerates this folder from `www/` and `config.xml` on every build — treat it as disposable, compiled output.
`plugins/`	The installed source code of every Cordova plugin your project uses, along with metadata files (`fetch.json`) tracking exactly what was installed. Managed entirely through `cordova plugin add` / `remove` — you don't hand-edit files here.
`config.xml`	The app's manifest — a single XML file describing the app ID, name, version, author, permissions, and platform-specific settings. Important enough to get its own deep-dive on the next page.
`hooks/`	A place for custom scripts that Cordova will automatically run at specific points in the build lifecycle (e.g. `before_prepare`, `after_build`) — useful for things like auto-generating a build number, but not something a beginner project needs to touch.
`res/` and `merges/`	Platform-specific overrides. `res/` commonly holds source icon and splash-screen images; `merges/` lets you drop in files that get merged into a specific platform's copy of `www/` only — handy for small per-platform tweaks without branching your whole codebase.

The golden rule: www/ is the only folder a Cordova developer should be manually editing. Everything else is either generated, managed by the CLI, or configuration metadata — hand-editing platforms/ in particular is a classic mistake, because your changes are silently thrown away the next time Cordova rebuilds.

Why You Should Never Hand-Edit `platforms/`

It's tempting, especially when debugging a native-looking issue, to open the generated Android or iOS project inside platforms/ directly and start changing files. Resist this. The entire purpose of that folder is to be a disposable build artifact: Cordova is free to delete and regenerate it at any time (for example when you run cordova platform rm android followed by cordova platform add android, a common troubleshooting step), and any hand-edits you made will simply vanish. If you genuinely need to customize native-level configuration, the supported approaches are editing config.xml, writing a plugin, or using a hook script — never editing generated platform files in place.

What Happens When You Run `cordova build`

Understanding the build step demystifies why www/ is so central. When you run:

cordova build

Cordova performs, roughly, three steps for every platform currently added to the project:

Step	What Happens
1	Cordova reads `config.xml` to determine app metadata, preferences, and which plugins should be present
2	It copies the entire contents of `www/` into the appropriate location inside each platform's project folder under `platforms/` (this step is called "preparing")
3	It invokes that platform's native build tool — Gradle for Android, `xcodebuild` for iOS — to compile the native wrapper and package your web assets into an installable app (an APK/AAB for Android, an IPA for iOS)

In other words, every build starts fresh from your www/ source and your config.xml settings — which is exactly why editing generated files inside platforms/ is pointless; the next build overwrites them anyway.

A Closer Look Inside `www/`

The default www/ folder that cordova create generates is deliberately simple, but it establishes a pattern worth keeping as your app grows:

Path	Contains
`www/index.html`	The single entry page loaded into the WebView, referenced by `<content src="index.html" />` in `config.xml`
`www/css/`	Your stylesheets — plain CSS, or the compiled output of a preprocessor/framework if you use one
`www/js/`	Your application JavaScript, including the `deviceready` listener and any code that talks to plugins
`www/img/`	Images and other static assets referenced by your HTML/CSS

There's nothing magic about this layout — Cordova only cares that index.html exists at the path named in config.xml. Everything else under www/ is served up to the WebView exactly as you organize it, so feel free to add build tooling (a bundler, a CSS preprocessor, a JavaScript framework) as long as the final compiled output still lands inside www/ before you build.

Version Control: What to Ignore

Because platforms/ and plugins/ are fully regenerated from config.xml and www/, committing them to source control is unnecessary bloat — they can (and generally should) be excluded with a .gitignore file so your repository only tracks the files you actually authored:

platforms/
plugins/
node_modules/

Anyone who clones the repository can fully regenerate platforms/ and plugins/ by running cordova prepare (or simply cordova build, which prepares automatically), since every platform and plugin dependency is already recorded in config.xml.

Next: Now that you know what every generated folder does, dive into config.xml Deep Dive to understand the one file you'll edit most often outside of www/.

Previous Next