Before converting a ZIP to an APK, make sure index.html is at the root of the archive, every link is relative, file names match their references exactly (Android is case-sensitive), no required file loads from a CDN, single-page apps use hash routing, and the zipped size is under the plan limit — 5 MB free or 18 MB on Pro.
The checklist
Structure
- index.html at the root, or inside a single wrapping folder (the builder unwraps it).
- Only the build output. Zip
dist/orbuild/, not the project withnode_modules/,src/and.git/. - Standard ZIP. Right-click → Compress (macOS) or Send to → Compressed folder (Windows). Not RAR, 7z or an encrypted ZIP.
Paths and names
- Relative links everywhere — HTML, CSS
url(), JS loaders andfetch()calls. - Exact case.
Hero.JPGandhero.jpgare different files on Android. - Link to files, not folders.
guide/index.html, notguide/. - Prefer lower-case, hyphenated names without spaces. They work, but other tools trip on them.
Behaviour
- No CDN dependencies for anything needed offline.
- Hash routing for React, Vue, Angular and Svelte SPAs.
- No dev URLs: no
localhost, LAN IPs or staging API bases.
Size
- Under the limit zipped — 5 MB free, 18 MB Pro. Delete
*.mapsource maps, keep only WOFF2 fonts, convert images to WebP. - No stowaways:
.DS_Store,Thumbs.db, PSD/AI source files, unused videos.
Run your archive through the ZIP structure checker: it reads the ZIP in your browser and reports the start page, case issues, root paths, source maps and the size against both limits.
Zipping correctly on each OS
| OS | Do this |
|---|---|
| macOS | Open the build folder, select all files inside, right-click → Compress. The __MACOSX folder it adds is ignored. |
| Windows | Open the folder, select all, right-click → Send to → Compressed (zipped) folder. |
| Linux / CI | cd dist && zip -r ../app.zip . |
| Android phone | Files by Google → select files → Compress, or ZArchiver. |
Questions people ask
Should I zip the folder or its contents?
Either works: the builder unwraps a single top-level folder. Zipping the contents is cleaner and avoids the start page being guessed.
Why does the builder open the wrong page?
It picks index.html at the root first. If your archive has a template index.html at the root and the real one in dist/, the template wins. Zip the contents of dist/ instead.
Are source maps needed in the APK?
No. Users cannot open DevTools on a release app, so .map files only add size. Delete them before zipping.