DOCSEARCHbyAlgolia
Submit Docs

WebToApp Documentation

repository·main·Indexed 26 days ago

https://github.com/shiaho777/web-to-app

An on-device Android workshop for building, signing, and deploying APKs and AABs directly from a mobile device. WebToApp supports full server runtimes (Node.js, PHP, Python, Go), advanced networking like TLS fingerprint spoofing and ECH, and a decentralized Module Market for extending functionality via JavaScript modules.

Tokens
57.5K
Snippets
43
Records
385
Agent score
90%

What's inside WebToApp

  1. Overview of WebToApp capabilities

    main

    WebToApp is an on-device APK workshop for Android (version 23+) that allows you to build Android APKs from web projects directly on your phone without a PC or remote build server.

    Key capabilities include:

    • On-device Server Runtimes: Runs Node.js (18.20), PHP (8.4 + Composer 2.10), Python (3.14), Go (1.26), and WordPress (7.x over SQLite) as native binaries.
    • Advanced Networking: Includes a hardened anti-censorship stack with DNS-over-HTTPS (DoH), TLS fingerprint spoofing (Chrome/Firefox/Safari JA3 templates), Encrypted Client Hello (ECH) via GeckoView, and CORS bypass.
    • Self-contained Build System: Performs AXML/ARSC patching, permission pruning, and V1/V2/V3 signing, including Google Play-ready AAB export.
    • Extensibility: Supports JS/CSS modules, Tampermonkey-style userscripts (GM_*), and MV3 Chrome extensions via live Chrome Web Store search.
    • AI Coding: Prompt-driven generation of web apps, modules, userscripts, and runtime projects.

  2. Overview of Common Config capability cards

    main

    The Edit Common Config editor is organized into several functional groups of capability cards. These settings are shared across app types. The available configuration categories are:

    • Basic info: App Icon, App Name, URL / Webpage
    • Browser & interface: Hide Browser Toolbar, Fullscreen Mode, Screen Orientation, Keep Screen On, Floating Window, Long-press Menu
    • Media & interaction: Splash Animation, Background Music, Popup Announcement, Webpage Auto Translation
    • Extensions & network: Extension Modules, Ad Blocking, Custom DNS
    • Disguise: Icon & App, Device Disguise
    • Launch & runtime: Auto-start, Forced Run, BlackTech
    • Advanced & export: Advanced Settings, Special Settings, APK Export Config

  3. Overview of WebToApp extension types

    main

    WebToApp supports four types of extensions that are managed by a single ExtensionManager and injected by the WebView at various page-lifecycle hooks. Choose a type based on your use case:

    • JS Module: Requires a module.json manifest and a main.js (plus optional CSS). Best for custom features with a configuration UI and floating panels.
    • CSS Module: A pure style override. Requires a main.js stub.
    • Userscript: Tampermonkey/Greasemonkey-style .user.js files. Best for porting existing userscripts; supports GM_* APIs.
    • Chrome MV3: A Manifest V3 Chrome extension. Best for porting browser extensions; supports chrome.* APIs.

  5. Understand the WebToApp repository layout

    main

    The repository is organized into several key modules that define the builder host, the runtime template, and the module market:

    • app/: The main application module (builder host). Contains the editor UI, export pipeline, runtimes, and preview functionality.
    • shell/: The runtime template. This is built into app/src/main/assets/template/webview_shell.apk using the :shell:assembleRelease and :app:syncShellTemplateApk tasks.
    • clone-host/: A library for APK cloning and identity reshaping, compiled to a DEX asset.
    • modules/: The Module Market catalog, containing registry.json and individual module folders.
    • scripts/: Build helpers and validation scripts (e.g., check_config_field_drift.py).
    • docs/: The documentation site.

  6. Distinguish between Common and Core configuration

    main

    WebToApp uses two distinct configuration layers:

    1. Common config: Shared capability cards that every app has access to (e.g., Appearance, Privacy, Network).
    2. Core config: Type-specific settings related to the source or runtime of the app. These are found in the Edit Core Config interface and vary depending on the specific app type.

  8. Understand WebToApp Architecture

    main

    WebToApp is composed of three primary Gradle modules:

    • app: The full builder and host application.
    • shell: The runtime host that is embedded into the generated APKs.
    • clone-host: Host code used for app cloning. This is compiled to a classes.jar, converted to DEX via d8, and bundled as an asset for AppCloner.

    Key architectural details:

    • Runtime Source of Truth: Runtime code is authored in app and synchronized into shell (e.g., core/shell, core/webview, core/engine).
    • APK Patching: The builder patches template APKs at the binary AXML/ARSC level, injects resources, prunes permissions, and signs them using apksig.
    • Target SDK: The host pins targetSdk = 28 to allow generated apps to fork+exec native runtimes (like Node.js, PHP, Python, Go, or WordPress) from app storage.
    • On-demand Assets: Heavy native artifacts like GeckoView native libraries (.so + omni.ja) and server runtimes are downloaded on first use rather than bundled in the base APK.

  9. Understand WebToApp app definitions and build process

    main

    WebToApp manages app definitions as WebApp records in a local Room database (web_apps table). Each definition includes:

    • Identity: name, url, iconPath, packageName, and appType.
    • Type-specific config: Depending on the appType, this includes mediaConfig, galleryConfig, htmlConfig, wordpressConfig, nodejsConfig, phpAppConfig, pythonAppConfig, goAppConfig, or multiWebConfig.
    • Feature flags + configs: Includes settings for activation, ads, announcement, ad blocking, WebView settings, splash, background music, translation, extensions, auto-start, disguise, and apkExportConfig for packaging.

    Build Process: The builder takes a shell template APK, patches its identity and resources, embeds your WebApp configuration as an assets JSON, and signs the result to produce a standalone APK.

  11. Manage server-runtime binaries in Runtime Management

    main

    The Runtime Management module allows you to download, control, and clean up the binaries used by your apps.

    Supported Runtimes

    • PHP runtime
    • WordPress core
    • Node.js runtime
    • Python runtime
    • Go runtime

    Available Actions and Features

    • Download Control: You can use Download all to fetch all runtimes at once, or use Pause, resume, or cancel on individual downloads. You can monitor status (ready/missing) and download progress.
    • Cleanup: Use Clear to remove a specific runtime or Clear all (requires confirmation) to wipe all managed runtimes.
    • Filtering: Filter the list by show all, only missing, or only ready.
    • Mirroring: The system uses automatic mirror selection, but you can manually select a CN mirror option if needed.

    Important Notes

    • Caching: Runtimes are downloaded on first use and cached for reuse across different apps.
    • Large Downloads: The system uses an extended-timeout download client for large files to prevent failures.
    • Build Dependencies: For toolchains and build dependencies, refer to the Linux Environment guide.

  12. Manage module versioning and updates

    main

    When publishing an update, you must synchronize version numbers in two places:

    1. In module.json: Update version.code (integer) and version.name (string).
    2. In registry.json: Update version (the string matching version.name).

    The client uses semver to compare the installed version against the registry and offers a one-tap upgrade.

    Config Preservation:

    • Keys declared in the new configItems will retain their existing values.
    • Keys removed from the new manifest will be cleaned up from the user's storage.
    • Warning: Renaming a config key is treated as a deletion and a new addition, which resets the value to the default. Document such changes in version.changelog.