Cordova Android App Development: Complete Setup Guide

Overview

What is Cordova? Cordova wraps your HTML/CSS/JavaScript web app in a native Android container, allowing it to run as a standalone app on Android devices. Having suffered through getting this all setup via Claude.ai I thought I would ask Claude.ai to write this guide.

What you’ll need:

• A computer running Linux (Ubuntu/similar)
• An HTML/CSS/JavaScript web page
• About 1-2 hours for initial setup
• 2-3 GB of disk space for all the tools

---

Part 1: Understanding the Components

1.1 Core Components You Need

Component	Purpose	Version to Use
Node.js	JavaScript runtime needed to run Cordova	Latest LTS (v22+)
npm	Package manager (comes with Node.js)	Comes with Node
Java JDK	Required by Android build tools	OpenJDK 17
Android SDK	Tools to build Android apps	Latest (34+)
Gradle	Build automation tool for Android	8.7+
Cordova	The framework that wraps your web app	Latest (12+)
Cordova Android	Android platform for Cordova	13.0.0 (stable)

1.2 Why These Specific Versions?

Node.js LTS: “Long Term Support” = stable and well-tested OpenJDK 17: Required by modern Android build tools Cordova Android 13.0.0: Version 14+ has bugs; 13 is stable and works Android SDK 34: Current stable version (as of late 2024/early 2025)

---

Part 2: Installation (One-Time Setup)

2.1 Install Node.js and npm

# Install nvm (Node Version Manager) - makes version management easy
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Reload your shell
source ~/.bashrc

# Install the latest LTS version of Node.js
nvm install --lts
nvm use --lts

# Verify installation
node --version  # Should show v22.x.x or similar
npm --version   # Should show 10.x.x or similar

2.2 Install Java JDK

# Update package list
sudo apt-get update

# Install OpenJDK 17
sudo apt-get install -y openjdk-17-jdk

# Set JAVA_HOME environment variable
echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' >> ~/.bashrc
source ~/.bashrc

# Verify installation
java -version  # Should show "openjdk version 17.x.x"

2.3 Install Android SDK

# Create Android SDK directory
mkdir -p ~/Android/Sdk/cmdline-tools

# Download Android command line tools
cd /tmp
wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip

# Extract to the correct location
unzip commandlinetools-linux-*.zip -d ~/Android/Sdk/cmdline-tools/
mv ~/Android/Sdk/cmdline-tools/cmdline-tools ~/Android/Sdk/cmdline-tools/latest

# Set environment variables
echo 'export ANDROID_HOME="$HOME/Android/Sdk"' >> ~/.bashrc
echo 'export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools"' >> ~/.bashrc
source ~/.bashrc

# Accept licenses and install required packages
yes | sdkmanager --licenses
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"

# Verify installation
sdkmanager --list_installed

2.4 Install Gradle

# Download Gradle
cd /tmp
wget https://services.gradle.org/distributions/gradle-8.10.2-bin.zip

# Extract to /opt
sudo unzip -d /opt gradle-8.10.2-bin.zip
sudo ln -s /opt/gradle-8.10.2 /opt/gradle

# Add to PATH
echo 'export PATH="$PATH:/opt/gradle/bin"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
gradle --version

2.5 Install Cordova

# Install Cordova globally via npm
npm install -g cordova

# Verify installation
cordova --version  # Should show 12.x.x or similar

---

Part 3: Creating Your First App

3.1 Create a Cordova Project

# Syntax: cordova create <directory> <package-id> <app-name>
# Example:
cordova create myapp com.yourname.myapp "My App"

# Navigate into the project
cd myapp

Package ID Rules:

• Use reverse domain notation: com.yourname.appname
• Must be unique (like: com.johnsmith.cardtrick)
• Only lowercase letters, numbers, and dots
• No spaces or special characters

3.2 Add Your Web Files

# Remove default Cordova files
rm -rf www/*

# Copy your HTML/CSS/JS files to www/
cp /path/to/your/index.html www/
cp /path/to/your/style.css www/
cp /path/to/your/script.js www/
cp -r /path/to/your/images www/

# IMPORTANT: Your main HTML file MUST be named index.html

3.3 Add Android Platform

# Add Android platform version 13.0.0 (stable)
cordova platform add android@13.0.0

# Verify it was added
cordova platform ls
# Should show: "Installed platforms: android 13.0.0"

Why version 13.0.0?

• Version 14+ has known bugs with missing gradle wrapper files
• Version 13 is stable and works reliably
• Explicitly specifying the version prevents issues

3.4 Create Network Security Config (Required)

This file is often missing and causes build failures. Create it manually:

# Create the directory
mkdir -p platforms/android/app/src/main/res/xml

# Create the config file
cat > platforms/android/app/src/main/res/xml/network_security_config.xml << 'EOF'
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>
EOF

What this file does: Allows your app to make network requests. Required by Android for security purposes.

3.5 Build Your App

# Build the APK
cordova build android

# If successful, you'll see: "BUILD SUCCESSFUL"
# Your APK is located at:
# platforms/android/app/build/outputs/apk/debug/app-debug.apk

---

Part 4: Installing on Your Phone

4.1 Enable USB Debugging on Your Phone

1. Go to Settings > About Phone
2. Tap “Build Number” 7 times (enables Developer Options)
3. Go back to Settings > System > Developer Options
4. Enable “USB Debugging”

4.2 Connect and Install

# Connect your phone via USB cable

# Check if phone is detected
adb devices
# Should show your device with "device" status

# Install the app
cordova run android --device

# The app will install and launch automatically!

4.3 Manual Installation (Alternative)

If USB isn’t working:

1. Copy app-debug.apk to your phone (email, cloud storage, etc.)
2. On your phone: Settings > Security > Install Unknown Apps
3. Enable for your file manager
4. Open the APK file on your phone
5. Tap “Install”

---

Part 5: Common Issues and Solutions

Issue 1: “BUILD FAILED – network_security_config not found”

Solution: Create the network security config file (see section 3.4)

Issue 2: “gradlew not found” or “gradle wrapper missing”

Solution: Use Cordova Android version 13.0.0, not 14.x

cordova platform remove android
cordova platform add android@13.0.0

Issue 3: “Build tools version 35.0.0 not found”

Solution: Install the required build tools:

sdkmanager "build-tools;35.0.0"

Or downgrade to use what you have:

cat > platforms/android/cdv-gradle-config.json << 'EOF'
{
  "BUILD_TOOLS_VERSION": "34.0.0"
}
EOF

Issue 4: “JAVA_HOME not set”

Solution: Set the environment variable:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' >> ~/.bashrc

Issue 5: “cordova: command not found”

Solution: Reload your environment:

source ~/.bashrc
# Or close and reopen your terminal

Issue 6: Phone not detected by adb

Solution:

1. Try a different USB cable (data cable, not just charging cable)
2. Change USB mode on phone to “File Transfer” or “MTP”
3. Revoke USB debugging authorizations and reconnect
4. Check if phone shows authorization popup – tap “Allow”

---

Part 6: Making Changes and Rebuilding

6.1 Update Your App

cd ~/myapp

# Edit your files in www/
nano www/index.html  # or use your preferred editor

# Rebuild
cordova build android

# Reinstall on phone
cordova run android --device

6.2 Clean Build (When Things Break)

# Clean old build files
cordova clean

# Remove and re-add Android platform
cordova platform remove android
cordova platform add android@13.0.0

# Recreate network security config
mkdir -p platforms/android/app/src/main/res/xml
cat > platforms/android/app/src/main/res/xml/network_security_config.xml << 'EOF'
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>
EOF

# Build again
cordova build android

---

Part 7: Version Compatibility Chart

Known Good Combinations

Node.js	Cordova	Cordova Android	Android SDK	Result
22.x LTS	12.x	13.0.0	34	✅ Works
22.x LTS	12.x	14.0.1	35	❌ gradle wrapper issues
20.x LTS	12.x	13.0.0	34	✅ Works
18.x	12.x	12.0.1	33	✅ Works

Version Check Commands

# Check all versions
node --version
npm --version
java -version
cordova --version
gradle --version
sdkmanager --list_installed

---

Part 8: Directory Structure Explained

myapp/                          # Your project root
├── config.xml                  # App configuration (name, ID, permissions)
├── package.json                # npm dependencies
├── www/                        # YOUR WEB FILES GO HERE
│   ├── index.html             # Main HTML file (required name)
│   ├── css/                   # Your stylesheets
│   ├── js/                    # Your JavaScript
│   └── img/                   # Your images
├── platforms/                  # Generated platform code
│   └── android/               # Android-specific files (auto-generated)
│       └── app/build/outputs/apk/debug/
│           └── app-debug.apk  # YOUR COMPILED APP
└── plugins/                    # Cordova plugins (if you add any)

Important:

• Only edit files in www/ – everything in platforms/ is auto-generated
• Don’t manually edit files in platforms/android/ – they get overwritten
• Exception: network_security_config.xml needs manual creation

---

Part 9: Quick Reference Commands

Project Setup

cordova create <dir> <id> <name>    # Create new project
cd <dir>                             # Enter project
cordova platform add android@13.0.0  # Add Android platform

Build and Run

cordova build android                # Build APK
cordova run android --device         # Install on connected phone
cordova clean                        # Clean build files

Platform Management

cordova platform ls                  # List installed platforms
cordova platform remove android      # Remove Android platform
cordova platform add android@13.0.0  # Add specific version

Debugging

adb devices                          # List connected devices
adb logcat                           # View Android logs
cordova requirements                 # Check if all tools installed

---

Part 10: Tips for Success

✅ DO:

• Use Cordova Android version 13.0.0 (stable)
• Create the network security config file manually
• Keep your main file named index.html
• Test in a browser first before building for Android
• Use source ~/.bashrc after installing new tools
• Run cordova clean if builds start failing

❌ DON’T:

• Use Cordova Android 14.x (has bugs)
• Run gradle directly – use cordova build instead
• Edit files in platforms/android/ manually
• Forget to enable USB debugging on your phone
• Skip setting environment variables (JAVA_HOME, ANDROID_HOME)

💡 Pro Tips:

1. Save this version combo: Cordova 12.x + Android 13.0.0 + SDK 34
2. When in doubt, clean rebuild: Remove platform, re-add, rebuild
3. Browser first: Test your HTML in browser before building APK
4. Version lock: Always specify @13.0.0 when adding Android platform
5. Environment check: Run source ~/.bashrc if commands aren’t found

---

Part 11: Alternative: PWA (Progressive Web App)

If you don’t need native features, consider making a PWA instead:

Pros:

• ✅ No complex build process
• ✅ No version conflicts
• ✅ Instant updates (no reinstall needed)
• ✅ Works offline with service worker
• ✅ Installs like an app on Android

Cons:

• ❌ Limited access to native features (camera, GPS, etc.)
• ❌ Requires web hosting (but free options exist)

Quick PWA Setup:

1. Add manifest.json (app metadata)
2. Add service-worker.js (offline support)
3. Upload to web host (GitHub Pages, Netlify, etc.)
4. Users visit in Chrome → “Add to Home Screen”

For simple apps without native features, PWA is the KISS solution!

---

Summary: The Minimum Viable Setup

If you just want to get started quickly:

# 1. Install Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts

# 2. Install Java
sudo apt-get install openjdk-17-jdk

# 3. Install Android SDK (simplified)
# Download from: https://developer.android.com/studio#command-tools
# Extract and set ANDROID_HOME

# 4. Install Cordova
npm install -g cordova

# 5. Create and build
cordova create myapp com.me.myapp MyApp
cd myapp
# Copy your HTML to www/
cordova platform add android@13.0.0
# Create network_security_config.xml (see section 3.4)
cordova build android

Total time: 1-2 hours for first-time setup
Subsequent apps: 10-15 minutes

---

Troubleshooting Checklist

When something goes wrong, check these in order:

• [ ] Are you in a Cordova project directory? (ls config.xml should work)
• [ ] Did you run source ~/.bashrc after installing tools?
• [ ] Is JAVA_HOME set? (echo $JAVA_HOME should show path)
• [ ] Is ANDROID_HOME set? (echo $ANDROID_HOME should show path)
• [ ] Are you using Cordova Android 13.0.0? (cordova platform ls)
• [ ] Does network_security_config.xml exist? (see section 3.4)
• [ ] Did you rebuild after making changes? (cordova build android)
• [ ] Is your phone in USB debugging mode and authorized?

If all else fails:

cordova clean
cordova platform remove android
cordova platform add android@13.0.0
# Recreate network_security_config.xml
cordova build android

---

Final Words

Cordova is powerful but complex. The key to success:

1. Use proven versions (Cordova Android 13.0.0)
2. Follow the steps exactly (especially network_security_config)
3. Don’t skip environment variables (JAVA_HOME, ANDROID_HOME)
4. Use Cordova commands (not gradle directly)
5. Clean rebuild when stuck (it fixes 90% of issues)

Once you have it working once, subsequent apps are much easier!

Good luck! 🎴📱