\n
\n Convert HTML/CSS/JS into a real Android APK — with zero Android knowledge.\n
\n\n Quick Start •\n Configuration •\n How It Works •\n Comparison\n
\n\n\n---\n\n## What's New in v1.3.1\n- 🐛 **SQUASHED: Keystore Password Validation Bug:** Fixed an issue during `nitron keystore` where the password confirmation step would incorrectly fail with \"Passwords do not match\" or crash, even when the passwords matched exactly.\n\n---\n\n## What's New in v1.3.0 (The \"White Screen & Missing Icon\" Terminator Update)\n- 🐛 **SQUASHED: The White Screen of Death (Framework Absolute Paths):** \n Fixed a massive issue where React/Vue apps built with absolute paths (`src=\"/static/js/main.js\"`) resulted in a blank white screen. Android's WebView reads `/` as the root of the entire phone file system (`file:///`), not `android_asset/`. We implemented an intelligent path rewriting engine in `injector.ts` to convert absolute paths to relative paths (`./`) on the fly, guaranteeing any web framework output runs flawlessly.\n- 🐛 **SQUASHED: The Invisible App Icon (Adaptive Icon XML Drama):** \n Fixed an incredibly obscure, ridiculous Android bug where the adaptive icon wouldn't render, defaulting to the generic Android robot. The culprit? We were using `android:color` instead of `android:drawable` for the adaptive icon background layer inside the `aapt2` generator. Modern launchers silently reject `android:color` in this context. Nitron now outputs 100% compliant `ic_launcher.xml` structures matching Android Studio exactly!\n- ✅ **Custom Adaptive Icon Backgrounds:** You can now pass an object to `icon` in `app.js` to set a custom background color alongside your foreground image! (`{ src: \"image.png\", background: \"#000000\" }`)\n- ✅ **New CLI Flag (`--project`):** Build an APK from any directory without changing your `cwd`!\n- ✅ **Bypassed AXML Encoder:** We fully migrated manifest generation from our fragile custom AXML binary encoder to `aapt2 link`, meaning the generated APK's `AndroidManifest.xml` is 100% native, flawless, and Google Play compliant.\n\n---\n\n## What's New in v1.2.0\n- ✅ Linux and Mac support\n> **Note:** Linux and Mac support is implemented but not yet tested on physical machines. Community feedback welcome — if you encounter issues, please open a GitHub issue.\n- ✅ Custom dev server port (`--port`)\n- ✅ Improved permissions validation\n- ✅ Multi-page navigation support\n- ✅ Tested with React and Vue\n- ✅ Android compatibility table\n- ✅ Dependency updates and security improvements\n\n---\n\n## The Problem\n\nEvery tool that turns web apps into Android apps eventually forces you to open Android Studio, install Gradle, configure a JDK, and think like an Android developer.\n\nCapacitor says \"web-first\" — then asks you to install Android Studio. \nCordova says \"cross-platform\" — then requires 8GB of RAM for a build. \nPWAs can't ship on Google Play as real apps.\n\n**Nitron makes Android completely invisible — not just simpler.**\n\nYou write HTML, CSS, and JavaScript. You run an npm command. You get a real `.apk` file. That's it.\n\n---\n\n## Quick Start\n\n```bash\nnpx nitron init my-app\ncd my-app\nnpm run dev # to preview locally\nnpm run build # to generate APK\n```\n\n**Output:** `dist/app.apk` — a real Android APK, ready to install on any device or upload to Google Play.\n\nNo Android Studio. No Gradle. No SDK. Just npm and a Java runtime.\n\n---\n\n## Configuration\n\nAll app settings live in a single `app.js` file:\n\n```javascript\nimport { app } from 'nitron'\n\napp.init({\n name: \"My App\",\n packageId: \"com.myname.myapp\",\n version: \"1.0.0\",\n entry: \"index.html\",\n orientation: \"portrait\",\n permissions: [\"INTERNET\", \"CAMERA\"],\n icon: \"./assets/icon.png\"\n})\n```\n\n### Options\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `name` | `string` | **required** | App display name on the device |\n| `packageId` | `string` | **required** | Unique Android package ID (e.g. `com.myname.myapp`) |\n| `version` | `string` | `\"1.0.0\"` | App version |\n| `entry` | `string` | `\"index.html\"` | HTML entry point loaded by the app |\n| `orientation` | `string` | `\"portrait\"` | `portrait` / `landscape` / `auto` |\n| `statusBar` | `boolean` | `true` | Show or hide the Android status bar |\n| `permissions` | `string[]` | `[]` | Android permissions (e.g. `CAMERA`, `INTERNET`) |\n| `icon` | `string` or `Object` | `null` | Path to app icon image, or object: `{ src: \"icon.png\", background: \"#000000\" }` |\n\n---\n\n## How It Works\n\nNitron uses a pre-built Android WebView template. When you run `npm run build`, it executes an 8-step pipeline that produces a signed APK in seconds:\n\n```\nnpm run build\n │\n ▼\n[1] Read Config → Parse app.js + package.json\n[2] Validate → Check files exist, fields are valid\n[3] Unpack Template → Extract base WebView APK to temp dir\n[4] Inject Assets → Copy your HTML/CSS/JS into the APK\n[5] Patch Manifest → Write app name, package ID, permissions\n[6] Repack → Zip everything back into .apk format\n[7] Sign → Auto-sign with debug keystore\n[8] Output → dist/app.apk ✓\n```\n\nThe entire process takes seconds, uses ~200MB of RAM, and never shows you a single Android error message.\n\n> **Technical Note:** Unlike other tools that require a massive Android SDK installation, Nitron uses an auto-downloaded, lightweight `aapt2` sidecar (~5MB) to compile resources and manifest natively. This guarantees 100% compliant `AndroidManifest.xml` and adaptive icons, with zero setup required from the developer.\n\n---\n\n## Framework Compatibility\n\nNitron seamlessly bundles the output of any web framework. Build your app using your favorite tool, and point Nitron to the output directory (e.g. `dist/` or `build/`).\n\n- **React / Vite**: 100% compatible. Ensure you use relative paths in your build config (`base: './'`).\n- **Vue**: 100% compatible.\n- **Vanilla JS**: 100% compatible.\n\n---\n\n## Supported Android Versions\n\n| Android Version | API Level | Supported |\n|---|---|---|\n| Android 5.0 (Lollipop) | 21 | ✅ Min supported |\n| Android 9.0 (Pie) | 28 | ✅ |\n| Android 11 | 30 | ✅ |\n| Android 13 | 33 | ✅ |\n| Android 14 | 34 | ✅ Target SDK |\n| Android 16 | 36 | ✅ Tested |\n\n---\n\n## Comparison\n\n| Feature | Nitron | Capacitor | Cordova | PWA |\n|---|---|---|---|---|\n| Needs Android Studio | ❌ Never | ✅ Always | ✅ Always | — |\n| Needs Gradle | ❌ Never | ✅ Always | ✅ Always | — |\n| Needs Java / JDK | ⚠️ JRE only(minimal) | ✅ Always | ✅ Always | — |\n| npm-only workflow | ✅ Yes | ❌ No | ❌ No | ✅ Yes |\n| Real APK output | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |\n| Google Play ready | ⚠️ Need Tests | ✅ Yes | ✅ Yes | ❌ No |\n| Build time | Seconds | Minutes | Minutes | — |\n| RAM during build | ~200MB | 4–16GB | 4–8GB | — |\n| Setup time | ~60 seconds | 30–60 minutes | 30–60 minutes | Fast |\n| Error messages | Web-friendly | Android stacktraces | Android stacktraces | — |\n| iOS Support | ❌ No | ✅ Yes | ✅ Yes | ⚠️ Partial |\n\nJRE 8+ required for APK signing. No JDK, no Android SDK, no Gradle.\n---\n\n## Project Structure\n\nA Nitron project looks like any web project:\n\n```\nmy-app/\n├── index.html ← Your app UI\n├── style.css ← Your styles\n├── main.js ← Your logic\n├── app.js ← Nitron config\n└── package.json ← npm config\n```\n\nNo `android/` folder. No `platforms/`. No `gradle.properties`. Just your web files.\n\n---\n\n## Current Status\n\n| Phase | Status | Description |\n|---|---|---|\n| Phase 1 | ✅ Complete | CLI scaffold, config reader, validator |\n| Phase 2 | ✅ Complete | APK Build Pipeline (unpack → inject → sign) |\n| Phase 3 | ✅ Complete | Developer Experience Polish (`init` and `dev`) |\n| Phase 4 | ✅ Complete | Multi-Target Output (APK + PWA) |\n| Phase 5 | ✅ Complete | Publishing Helpers, release signing |\n\n---\n\n## Production Release\n\nWhen you are ready to publish your Android app to Google Play, you need a release keystore.\n\n1. Generate a keystore (only do this once!):\n ```bash\n npx nitron keystore\n ```\n2. Build for release:\n ```bash\n npx nitron build --release\n ```\n You will be prompted for your keystore password, and Nitron will generate a release-signed APK along with a Google Play checklist.\n\n---\n\n## Multi-Target Output (PWA)\n\nNitron can build both an Android APK and a Progressive Web App (PWA) from the exact same configuration.\n\n```bash\nnpx nitron build --target android # Default: Generates dist/app.apk\nnpx nitron build --target pwa # Generates dist/pwa/\nnpx nitron build --target all # Generates both\n```\n\nWhen building for `--target pwa`, Nitron automatically:\n- Copies your assets to `dist/pwa/`\n- Generates a fully compliant `manifest.json` based on `app.js`\n- Generates a `service-worker.js` that caches all your assets for offline use\n- Injects the necessary tags into your `index.html`\n\n---\n\n## Requirements\n\n- **Node.js** 18 or later\n- **npm** (comes with Node.js)\n- **Java Runtime** 8+ (for APK signing only — auto-detected)\n\nThat's it. No Android SDK, no Android Studio, no Gradle.\n\n---\n\n## Contributing\n\nContributions are welcome! Nitron is an open-source project and community feedback is what makes it better.\n\n### How to contribute\n\n1. Fork the repository\n2. Create a new branch: `git checkout -b feat/your-feature`\n3. Make your changes\n4. Run the build: `npm run build`\n5. Test locally: `node dist/cli.js build`\n6. Commit and push: `git commit -m \"feat: your feature\"`\n7. Open a Pull Request\n\n### What we need help with\n\n- Testing on Linux and Mac (most needed right now)\n- Testing with different web frameworks (React, Vue, Svelte, etc.)\n- Testing on different Android versions\n- Bug reports and edge cases\n\n### Reporting issues\n\nPlease open a GitHub issue with:\n- Your OS and version\n- Node.js version\n- The full error message\n- Steps to reproduce\n\n---\n\n## License\n\n[MIT](LICENSE) © [ALightbolt4G](https://github.com/ALightbolt4G)","readmeFilename":"README.md"}