pwa2apk

Convert PWA manifest URLs to native-looking Android APKs using WebView.

Why not bubblewrap/TWA? Chrome's Trusted Web Activity (TWA) shows a mandatory "Running in Chrome" privacy disclosure banner on every launch. There is no flag, API, or workaround to suppress it. pwa2apk uses a plain Android WebView instead of delegating to Chrome, so there is no banner, no Digital Asset Links ceremony, and no Chrome dependency.

Usage

# Basic — fetch manifest, build debug APK
npx pwa2apk https://example.com/manifest.json

# Full options
npx pwa2apk https://example.com/manifest.json \
  --package com.example.myapp \
  --keystore /path/to/keystore.jks \
  --keystore-alias myalias \
  --keystore-password mypass \
  --output ./myapp.apk

# Programmatic (for cua-sandbox integration)
const { buildApk } = require('pwa2apk');
const { apkPath, packageName } = await buildApk({
  manifestUrl: 'https://example.com/manifest.json',
  packageName: 'com.example.myapp',
  keystore: '/path/to/keystore.jks',
  keystoreAlias: 'myalias',
  keystorePassword: 'mypass',
});

How it works

1. Fetches the PWA Web App Manifest
2. Downloads icons (with SVG-to-PNG conversion fallback)
3. Generates a minimal Android project from a built-in template:
   • MainActivity with fullscreen WebView
   • Service Worker support via WebView
   • Theme colors from manifest
   • Back-button navigation
   • Splash screen with app icon
4. Builds a signed release APK using Gradle

Requirements

• Node.js >= 18
• JDK 17+ (JAVA_HOME must be set)
• Android SDK (auto-detected from ANDROID_HOME / ANDROID_SDK_ROOT, or uses the cua-sandbox managed SDK at ~/.cua/android-sdk)

Architecture

PWA Manifest URL
       │
       ▼
  Fetch & Parse ──► icons, name, colors, start_url, orientation
       │
       ▼
  Generate Android Project (from built-in template)
       │  - WebView-based MainActivity
       │  - No Chrome/CustomTabs dependency
       │  - Fullscreen, hardware-accelerated
       │
       ▼
  Gradle assembleRelease
       │
       ▼
  Signed APK ──► ready to install via adb/pm

Comparison with bubblewrap/TWA

Feature	bubblewrap (TWA)	pwa2apk (WebView)
"Running in Chrome" banner	Always shown	Never shown
Digital Asset Links needed	Yes	No
Chrome dependency	Required	None
Service Worker support	Full (via Chrome)	Partial (WebView)
Push notifications	Yes (via Chrome)	No
Offline support	Yes	Yes (via WebView cache)
APK size	~2 MB	~200 KB