Wrapping a web app with Capacitor takes an afternoon. Getting a correct signed bundle onto Google Play takes longer, mostly because the expensive mistakes happen after the code works: a build with last week's web files, a versionCode you already used, an app ID you can never change.
Each of those costs a Play Console round trip, and for new personal accounts every wasted upload also eats into the closed-test window (12 testers opted in for 14 days; check your own Console for current numbers). So I put the checks in code, in front of the release build, instead of relying on memory.
This is what each check does and why. Everything below is plain Node and Gradle, no framework. The snippets come from the scripts I use; I've only tested them on macOS (Node 24, JDK 21, Capacitor 8), so treat Windows/Linux as untested.
1. Never build Android from stale web files
./gradlew bundleRelease packages whatever is currently inside android/app/src/main/assets/public. If you forgot npx cap sync android, you ship an old version of your app under a new version number.
The release script always runs the same three steps in order, and nothing else:
run('npm', ['run', 'build']); // fresh web build
run('npx', ['cap', 'sync', 'android']); // copy it into the Android project
gradle(['bundleRelease']); // only then build the bundle
Rule of thumb: your release command should be one command. If it's three commands you type by hand, one day you'll skip one.
2. Refuse to reuse a versionCode
Google Play rejects an upload whose versionCode is not higher than every one you've used. You find out after uploading, which is the slow way.
The script records the last release build and refuses to build again with the same code:
const last = JSON.parse(fs.readFileSync(LAST, 'utf8'));
if (v.code <= last.versionCode) {
fail(`versionCode ${v.code} was already used for your last release build.`,
'Run "npm run version:bump" first.');
}
A tiny version:bump script increments versionCode and versionName in android/app/build.gradle.
Honest limitation: this only knows about release builds made on this machine. It can't see what you uploaded from somewhere else, and if release/ is git-ignored a fresh clone starts with no history. It catches the common slip (rebuilding without bumping), not every case.
3. Block the placeholder appId
appId becomes the app's permanent identity on Google Play. You can't change it after publishing, so a leftover com.example.myapp is a mistake you want to catch before the first upload, not after.
if (/^com\.example\./.test(cfg.appId)) {
fail(`appId is still "${cfg.appId}".`, 'Set your own in capacitor.config.json.');
}
The doctor command checks the same thing earlier, plus the format (lowercase letters, numbers, dots), so you find out before you even start a build.
4. Don't build a release without a signing key (and never commit it)
A release bundle built without a configured keystore either fails late or isn't signed the way you expect. The script checks that android/keystore.properties exists before it starts Gradle, and a one-time command creates the key with keytool:
keytool -genkeypair -v -keystore keys/upload-keystore.jks \
-alias upload -keyalg RSA -keysize 2048 -validity 10000
Two things worth adding:
-
.gitignoreentries forkeys/,*.jks,*.keystoreandkeystore.properties - a loud reminder to back the key and password up somewhere else. With Play App Signing this is your upload key; lose it and you're waiting on a Google reset instead of shipping.
5. Check the toolchain before the 10-minute build
The most common first-build failure isn't your code, it's Java or the SDK. A doctor command that runs in a second saves a lot of confusing Gradle output:
✔ Node.js 24.5.0
✔ Java 21
✔ Android SDK
✔ appId com.yourname.notes
It looks for JDK 21+ (including the JDK bundled with Android Studio) and finds the Android SDK. In the full kit, the build step also writes android/local.properties with sdk.dir, so Gradle doesn't fail with "SDK location not found". (The open-source doctor below only checks; it doesn't write that file.)
What these checks don't cover
They don't make Google approve your app. Production access still depends on real testers using the app, updates during the test, and specific answers in the application, and a web app that is just a website in a frame can still be rejected under the minimum functionality policy. The checks only remove the self-inflicted failures.
Want the scripts instead of rebuilding them?
Two of them, the toolchain doctor and the version:bump script, are open source (MIT): https://github.com/snuglabtech/capacitor-play-preflight
I also packaged the whole set (doctor, setup, icon and splash generation, guided keystore, version guard, signed build) with a step-by-step guide and Play Console templates:
- Free: a guide to the 12-tester / 14-day closed test (day-by-day plan, tester messages, how to answer the production-access questions): https://snuglab.gumroad.com/l/closed-testing
- Kit ($21): https://snuglab.gumroad.com/l/webapp-to-play
Disclosure: both are mine. Tested on macOS only so far; feedback from Windows and Linux users is very welcome.
What's the build mistake that cost you the most time? I'm collecting them for the next version of the checks.
Top comments (0)