Prerequisites
Before you begin, install the following tools on your machine. Note that iOS builds require a Mac.
| Tool | Required For | Min Version | Link |
|---|
| Node.js | Both | 18.x+ | nodejs.org |
| npm | Both | 9.x+ | Included with Node |
| Android Studio | Android | Latest | developer.android.com |
| JDK 17 | Android | 17+ | adoptium.net |
| Xcode | iOS (Mac only) | 14+ | Mac App Store |
| CocoaPods | iOS | 1.13+ | sudo gem install cocoapods |
Project Setup
After downloading your ZIP from the generator, extract it and run:
Step 1 — Extract & Install
# Extract the ZIP, then:
cd your-app-name
npm install
Step 2 — Add Platforms
# Add Android
npx cap add android
# Add iOS (Mac only)
npx cap add ios
Step 3 — Sync Project
npx cap sync
# This copies config and plugins to native projects
Build for Android
Open in Android Studio
npx cap open android
Android Studio will open your project. Wait for Gradle sync to complete.
Build Debug APK (testing)
# In Android Studio:
Build → Build Bundle(s)/APK(s) → Build APK(s)
# Or via command line:
cd android
./gradlew assembleDebug
# Output: android/app/build/outputs/apk/debug/app-debug.apk
Build Release AAB (Play Store)
cd android
./gradlew bundleRelease
# Output: android/app/build/outputs/bundle/release/app-release.aab
Build for iOS
iOS builds require a Mac with Xcode installed. You also need an Apple Developer account ($99/year).
Install CocoaPods dependencies
cd ios/App
pod install
cd ../..
Open in Xcode
npx cap open ios
Select your Team under Signing & Capabilities. Ensure your Bundle ID matches what you set in the generator.
Build & Archive for App Store
Product → Archive
# Then: Window → Organizer → Distribute App
# Choose: App Store Connect → Upload
Icons & Splash Screen
Use @capacitor/assets to auto-generate all required sizes from your single source image.
# Install the tool
npm install @capacitor/assets --save-dev
# Place your source files:
resources/icon.png ← 1024×1024px, no transparency
resources/splash.png ← 2732×2732px, centered artwork
# Generate all sizes for Android & iOS:
npx capacitor-assets generate
# Sync to native projects:
npx cap sync
Icon requirements: 1024×1024 PNG, no alpha channel (no transparency). For adaptive icons on Android, keep the main subject within the center 72% of the canvas.
Sign Your Android App
Google Play requires a signed release build. Generate a keystore once and keep it safe forever.
Create a keystore
keytool -genkey -v \
-keystore my-release-key.jks \
-keyalg RSA -keysize 2048 \
-validity 10000 \
-alias my-key-alias
Add to android/app/build.gradle
android {
signingConfigs {
release {
storeFile file('../my-release-key.jks')
storePassword 'YOUR_STORE_PASSWORD'
keyAlias 'my-key-alias'
keyPassword 'YOUR_KEY_PASSWORD'
}
}
buildTypes {
release { signingConfig signingConfigs.release }
}
}
Never commit your keystore or passwords to Git. Add *.jks to your .gitignore.
Sign Your iOS App
iOS signing is handled inside Xcode using your Apple Developer account.
# 1. Enroll at developer.apple.com ($99/yr)
# 2. In Xcode: Signing & Capabilities tab
# → Check "Automatically manage signing"
# → Select your Team
# 3. Xcode will create provisioning profiles automatically
# 4. Product → Archive → Distribute App → App Store Connect
Publish to Google Play Store
- Go to play.google.com/console and pay the $25 one-time registration.
- Create a new app and fill in the store listing (title, description, screenshots).
- Upload your signed
.aab file under Production → Releases.
- Fill in content rating questionnaire.
- Set pricing (free/paid) and countries.
- Submit for review — typically approved in 1–3 days.
Publish to Apple App Store
- Create your app at appstoreconnect.apple.com.
- Fill in app metadata: name, subtitle, description, keywords, screenshots (6.7", 6.1", iPad).
- Upload your build via Xcode Organizer or the Transporter app.
- Select the uploaded build in App Store Connect.
- Submit for App Review — typically approved in 1–2 days.
Apple requires that WebView apps provide genuine value beyond what a mobile browser offers. Ensure your app has a distinct UI, offline functionality, or push notifications.
Troubleshooting
Gradle build fails
# Clean and rebuild
cd android && ./gradlew clean && cd ..
npx cap sync android
White screen / URL not loading
Ensure your website URL is HTTPS. Check capacitor.config.json — the server.url must be reachable from a device. Test on a real device, not just emulator.
CocoaPods error on iOS
sudo gem install cocoapods
cd ios/App && pod repo update && pod install
App rejected by Apple
Common reasons: app simply wraps a website without added value. Fix: add push notifications, offline page, or a loading indicator with branded UX. Refer to Apple's App Review Guidelines §4.2.
Back to Generator