⚡
web2appv0.1
DOCS
Official Documentationv0.1.0FUMADOCS ENGINE

web2app Developer Guide

Compile Next.js, Vite, React, Vue, Svelte, Python, or live URLs into standalone native Android, Windows, Debian, and Arch apps with zero runtime bloat.

// 01.1 Overview

Introduction & Motivation

Traditional desktop and mobile packaging toolchains (like Electron, Cordova, or standard hybrid shells) bundle a 150MB+ Chromium browser binary and separate Node.js runtime into every application. This leads to massive file sizes, high idle RAM consumption, and complicated configuration workflows.

web2app compiles directly to native operating system WebViews: It takes your web application (Next.js, Vite, React, static HTML) or a live web URL, bundles it into clean native wrappers, and generates a structured app/ directory containing ready-to-run packages for Android, Windows, Debian/Ubuntu, and Arch Linux.

📱
Android APK
< 3 MB APK
🪟
Windows App
MS Edge App
🐧
Debian .deb
Pure TS Engine
🏹
Arch Linux
AUR PKGBUILD
// 01.2 Quick Start

Instant 10-Second Conversion

You can convert any live web URL or local project without installing anything beforehand using npx:

AConvert a Live Web Page URL

bash
npx web2app https://news.ycombinator.com

BConvert Current Project (Next.js / Vite / React / HTML)

bash
npx web2app build
When you run web2app build, the compiler auto-detects your web framework, compiles static production assets, copies native wrappers, and generates the complete app/ directory.
// 01.3 Installation

Installation & Script Runner Setup

web2app can be used as a global CLI, an npm devDependency with automated scripts in your package.json, or executed instantly via npx.

1. Global Installation (Recommended for Terminal Users)

bash
npm install -g web2app

2. Project DevDependency & NPM Scripts

Add web2app directly to your project dependencies so teammates and CI/CD pipelines can run automated build scripts:

bash
npm install -D web2app

Add these standard script targets to your package.json:

package.json
{
  "scripts": {
    "app:build": "web2app build",
    "app:android": "web2app build android",
    "app:windows": "web2app build windows",
    "app:debian": "web2app build debian",
    "app:arch": "web2app build arch",
    "app:doctor": "web2app doctor",
    "app:run": "web2app run android"
  }
}

3. Local Contributor Linking

Terminal
git clone https://github.com/FuadTesfaye/web2app.git
cd web2app
npm install
npm run build
npm link
// 01.4 Configuration Wizard

Project Initialization Wizard

Run web2app init inside your project root to interactively configure your app name, package ID, target platforms, and icons:

bash
web2app init
To skip interactive prompts and generate defaults automatically based on your package.json:
web2app init --yes
// 02.1 Architecture

Zero-Runtime Overhead Architecture

Traditional desktop frameworks package entire browser binaries, rendering engines, and Node.js runtimes into each application. web2app takes an architectural approach that relies on native operating system WebViews:

1

Android: AndroidX WebViewAssetLoader

Uses Android’s native WebKit with secure local asset loading, GPU hardware acceleration, and full HTML5 IndexedDB storage support.

2

Windows: MS Edge / Chromium App Mode

Leverages Microsoft Edge App Mode with custom window boundaries, silent VBScript launch runners, and Start Menu registry shortcuts.

3

Linux: Pure TypeScript DebPackager

Generates valid Debian binary .deb packages with XDG desktop application entries and scalable SVG/PNG icon hierarchies without requiring dpkg on the host machine.

// 02.2 Output Hierarchy

Unified app/ Directory Structure

When you run web2app build, the compiler produces clean, modular platform packages in ./app/:

app/ directory structure
app/
├── android/
│   ├── app-debug.apk                  # Compiled Android APK (if SDK available)
│   ├── app/src/main/                  # Kotlin source & AndroidManifest
│   └── gradlew                        # Ready to open in Android Studio
├── windows/
│   ├── launch.bat                     # Windows Batch Launcher (Edge App Mode)
│   ├── launch.ps1                     # PowerShell Runner
│   ├── start.vbs                      # Silent launcher (no command prompt)
│   ├── install.bat / install.ps1      # Creates Desktop & Start Menu shortcuts
│   ├── app.manifest / app.config.json # Manifest & Window Config
│   └── assets/                        # Bundled static web files
├── debian/
│   ├── <app-name>_<ver>_all.deb       # Standalone Debian/Ubuntu binary package
│   ├── DEBIAN/control                 # Package control metadata
│   └── usr/
│       ├── bin/<app-id>               # Linux executable launcher
│       ├── share/applications/*.desktop # Linux desktop shortcut
│       └── share/icons/               # App icon
└── arch/
    ├── PKGBUILD                       # Arch AUR-compatible build script
    ├── .SRCINFO                       # Arch package metadata
    ├── <app-id>.desktop               # Desktop entry
    ├── install.sh                     # Installation script (makepkg -si)
    └── <app-id>                       # Executable launcher
// 03.1 Target Platform

Android Packaging (APK / AAB)

The Android engine generates a lightweight Kotlin project utilizing modern androidx.webkit.WebViewAssetLoader.

npx web2app build android
// 03.2 Target Platform

Windows Desktop (WebView2 & App Mode)

Generates a standalone Windows Desktop application folder in app/windows/ with silent background launchers (start.vbs) and installation scripts.

bash
npx web2app build windows
// 03.3 Target Platform

Debian / Ubuntu (.deb) Binary Packages

web2app includes an internal, pure TypeScript DebPackager engine that constructs valid Unix ar archives and tar.gz payloads without requiring dpkg-deb on the build machine.

bash
npx web2app build debian
// 03.4 Target Platform

Arch Linux (PKGBUILD & AUR)

Generates standard Arch Linux PKGBUILD and .SRCINFO files compatible with makepkg -si and AUR publication.

bash
npx web2app build arch
// 04.1 Framework Guide

Next.js (App Router & Pages Router)

To bundle your Next.js application for offline execution inside standalone native apps, configure static HTML export in next.config.ts:

next.config.ts
// next.config.ts / next.config.mjs
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
  images: {
    unoptimized: true, // Required for static HTML export
  },
};

export default nextConfig;
If your Next.js application requires active server endpoints (e.g. Node.js Server Actions or dynamic API routes), deploy it to Vercel/Cloudflare and compile it as a Live Web URL:
npx web2app https://my-app.vercel.app --app-name "My App"
// 04.2 Framework Guide

Vite, React, Vue & Svelte

Vite and Single Page Applications work out of the box. Ensure your asset base path is set to relative (base: './'):

vite.config.ts
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  base: "./", // Relative asset paths for native file loaders
});
// 04.3 Framework Guide

Python (Streamlit, Flask, FastAPI)

For Python web applications, deploy your app or launch a local server and pass the URL to web2app:

bash
npx web2app http://localhost:8501 --app-name 'My Streamlit App'
// 05.1 CLI Reference

CLI Commands Reference

CommandDescriptionOptions
web2app [url]Converts a live URL into Android, Windows, Debian, and Arch apps--app-name, --out
web2app buildBuilds all target platforms into ./app/--release, --bundle, --out
web2app doctorDiagnoses Java JDK, Android SDK, ADB, and packaging tools-
web2app initInteractive setup wizard for web2app.config.ts--yes, --force
web2app run androidBuilds and installs APK onto connected emulator or device--device
web2app skillInstalls AI Agent Skill definition in .agents/skills/web2app--print, --force
// 05.2 Configuration Schema

web2app.config.ts Reference

Complete TypeScript interface for customizing application metadata, platform targets, orientation, permissions, and icons:

web2app.config.ts
import type { Web2AppUserConfig } from "web2app";

const config: Web2AppUserConfig = {
  appName: "My Web Application",
  packageName: "com.company.myapp",
  version: "1.0.0",
  versionCode: 1,

  // Target platforms to compile
  platforms: ["android", "windows", "debian", "arch"],

  // Android specific options
  android: {
    minSdk: 24,
    targetSdk: 35,
    orientation: "portrait", // "portrait" | "landscape" | "unspecified"
    permissions: [
      "android.permission.INTERNET",
      "android.permission.ACCESS_NETWORK_STATE",
    ],
  },

  // Linux (.deb & PKGBUILD) options
  debian: {
    categories: ["Network", "Utility"],
    maintainer: "Team <dev@company.com>",
  },
};

export default config;
// 06.1 AI Integration

AI Agent Skill Integration

web2app includes a standardized AI Assistant Skill formatted for Google Antigravity, Claude Code, Cursor, Windsurf, and Copilot.

Install the skill into your project with a single command:

bash
npx web2app skill
This creates .agents/skills/web2app/SKILL.md in your workspace. AI coding assistants will automatically detect frameworks, configure static exports, run doctor checks, and compile native targets.
// 06.2 AI Recipes

Ready-to-Use AI Prompt Recipes

Prompt: Full Project Conversion to Android
"Use the web2app skill to convert this web project into a standalone Android APK. Run web2app doctor, configure next.config.ts for static export if needed, build the APK, and verify the artifact."
Prompt: Multi-Platform Release Packaging
"Compile this web app for Android, Windows, Debian, and Arch Linux using web2app build. Verify the generated packages in the app/ directory."
// 07.1 Production

Android Keystore & APK Signing

For Google Play Store distribution, generate a release keystore and sign your production APK / AAB:

Generate Keystore
keytool -genkey -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-app-key
// 07.2 Automation

GitHub Actions CI/CD Pipeline

.github/workflows/build-apps.yml
name: Build Multi-Platform Native Apps

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'
      - name: Install dependencies
        run: npm ci
      - name: Build all native packages
        run: npx web2app build
      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: native-apps
          path: app/
// 08.1 Reference

Troubleshooting & FAQ

1. How do I fix "JAVA_HOME not set" during Android builds?

Install OpenJDK 17 or 21 (e.g. sudo apt install openjdk-21-jdk on Ubuntu or brew install openjdk@21 on macOS) and run web2app doctor.

2. Can I convert web apps with real-time WebSockets and IndexedDB?

Yes! All native WebViews (AndroidX WebKit, MS Edge WebView2, Linux WebKit) fully support modern HTML5 APIs including WebSockets, IndexedDB, Web Workers, Canvas, WebGL, and LocalStorage.

On this page