Docs
RepackOS turns a web app into a phone app. You keep your web app on your own server; the shell loads it full screen and adds native powers.
1. Describe your app
Each app is one JSON file in apps/. The file name is the app's key, for example apps/pileprofit.json.
{
"name": "PileProfit",
"appId": "com.yourcompany.app",
"teamId": "YOURAPPLETEAM",
"versionName": "0.1.0",
"versionCode": 1,
"startUrl": "https://your-web-app.com/app/",
"allowedHosts": ["your-web-app.com"],
"backgroundColor": "#121417",
"permissions": ["camera"],
"icon": "yourapp-icon.png",
"bridge": "NativeApp"
}| Field | What it does |
|---|---|
name | The name under the app icon. |
appId | Unique app ID, reverse-domain style. Never change it after you ship. |
versionName / versionCode | Version shown to people / whole number that must go up with every release. |
startUrl | The page the app opens on. Must be https. |
allowedHosts | Sites allowed to open inside the app. Anything else opens in the phone's browser. |
backgroundColor | Color behind the page while it loads, and of the system bars. |
permissions | Native powers the app may use. Today: "camera". |
teamId | Your Apple Developer Team ID. Your app is signed and published under your own account. |
icon | One 1024×1024 PNG, no transparency. Every icon size is made from it. |
bridge | Name of the JavaScript bridge your pages see. Optional, default NativeApp. |
userAgentTag | Optional word added to the browser ID so your server can tell app traffic apart. |
2. Build the Android app
Needs Android Studio installed (for its SDK and Java). Pass the app key with -Papp:
cd android
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
./gradlew assembleDebug -Papp=pileprofit
# app file: app/build/outputs/apk/debug/app-debug.apk3. Install it
With the phone connected (USB debugging on) or an emulator running:
adb install -r app/build/outputs/apk/debug/app-debug.apkYou can also send the .apk file to an Android phone and open it there (the phone will ask to allow installs from that source).
JavaScript bridge
Inside the app your pages get window.NativeApp (or the name you set in bridge). Check that it exists first, so the same page still works in a normal browser.
if (window.NativeApp) {
NativeApp.platform() // "android" or "ios"
NativeApp.version() // "0.1.0"
NativeApp.cameraStatus() // "granted" | "denied" | "prompt"
NativeApp.openAppSettings()
NativeApp.reload()
}Only pages from your allowedHosts are ever loaded inside the app, so only your own pages can reach the bridge.
How it behaves
- Camera: the first time your page asks for the camera, Android asks once (“Allow PileProfit to take pictures”). After that your pages get the camera with no prompt, even after the app is closed. Other sites never get it.
- Uploads:
<input type="file">opens the phone's file picker; multiple files work. - Back button: goes back in your web app; on the first page it closes the app.
- Login: cookies are kept between launches.
- No connection: a “No connection / Try again” screen; Try again reloads your start page.
- Screen edges: content is kept clear of the status bar, navigation bar and keyboard.
iPhone
The iPhone shell uses the same config file and a native Swift shell. Builds go to your own iPhone through TestFlight internal testing: private, no public listing, no review, and nothing is submitted to the App Store unless you choose to.
bash ios/testflight.sh pileprofitYour brand, not ours
Apps built with RepackOS carry your name, app ID, icon and Apple/Google account. The word “RepackOS” appears nowhere in the finished app.