How to structure an HTML project for APK conversion

A site that converts cleanly is not a different site — it is the same one, organised so that nothing depends on a web server being there. Three constraints drive every decision below: no server, a case-sensitive filesystem, and a file:// origin with browser restrictions attached.

A layout that works

my-app/
├── index.html          ← entry page, always at the root
├── pages/
│   ├── about.html
│   └── contact.html
├── css/
│   └── style.css
├── js/
│   └── app.js
├── img/
│   ├── logo.png
│   └── hero.webp
├── fonts/
│   └── inter-var.woff2
└── data/
    └── products.json

Nothing exotic — the point is that every reference between these files can be written relative to the file doing the referencing, and that the whole tree is self-contained.

Rules that matter more than the layout

Build tools: the settings that break bundled apps

If you use Vite, webpack, Parcel or similar, two defaults will cause trouble.

The base path. Bundlers default to absolute asset URLs (/assets/index-abc123.js), which is correct for a web server and wrong for a bundle. Set the base to relative:

// vite.config.js
export default { base: './' }

// webpack
output: { publicPath: './' }

Module output. A modern build emits <script type="module">, which does not load from file://. Either target a format that produces a classic script, or make sure the app serves your content over http://localhost rather than file://. Converters that bundle content usually do the latter — worth confirming rather than assuming.

Single-page apps and routing

A client-side router that uses the History API — /products/42 — depends on a server rewriting unknown paths back to index.html. There is no server. Deep links then 404 inside the app.

Hash routing (#/products/42) works everywhere with no server involvement, which is why it remains the right choice for bundled apps. Most routers support both; check which mode yours is in before you convert.

Storage and state

localStorage works in a WebView and persists between launches, but it is cleared when the user clears the app's data and it is not backed up. Treat it as a cache and a place for preferences, not as a database for anything the user would be upset to lose. Anything important belongs on a server.

Check the structure before you build

The fastest verification costs nothing: open your index.html directly from the file manager, not through a local server. That reproduces exactly the environment the app gives your pages.

• Does the page render styled and complete?
• Do the images appear?
• Does the console show CORS or 404 errors?
• Does navigation between pages work?

Whatever fails there will fail in the app. The validator catches the same class of problem statically, including several that are easy to miss by eye.

Before you package