🚀 What's New in v3.0.0

• iOS support (new engine: initron): Nitron now builds real iOS apps from the exact same nitron.config.json, using a WKWebView shell instead of Android's WebView. No Xcode is required — not even for the one-time shell build (see ARCHITECTURE.md §5–6 for the full breakdown of how).
  • nitron build --target ios-simulator — produces an unsigned .app, ready to test in the iOS Simulator. No Apple Developer account needed at all, since the Simulator doesn't require code signing.
  • nitron build --target ios — produces a signed .ipa for a real device, using zsign/ldid instead of Xcode's codesign. Requires an Apple Developer certificate — read from NITRON_IOS_P12_PATH, NITRON_IOS_P12_PASSWORD, NITRON_IOS_PROVISION_PATH.
  • One-time setup required: run scripts/build-ios-toolchain.sh + scripts/build-shell-device.sh once (or trigger .github/workflows/build-shell-device.yml, a plain Linux runner — no macOS anywhere in that path). Full details, every file, every design decision: ARCHITECTURE.md.
• Internal restructuring: the codebase is now split into two isolated engines — src/engines/nitronoid/ (Android, unchanged logic) and src/engines/initron/ (iOS, new) — sharing only a small platform-agnostic core. See ARCHITECTURE.md §2–4 for the full file-by-file map.
• Validated end-to-end: the full Linux → .ipa pipeline has been run for real (on Windows/WSL2), producing a genuine Mach-O arm64 binary, correct Payload/App.app/... structure, and an .ipa accepted by a real third-party iOS package validator (BrowserStack App Live). See ARCHITECTURE.md §10 for the exact issues hit and fixed along the way — useful reading if you hit something similar.

🚀 What's New in v2.1.0

• Google Play Protect Compliance: Completely secured the WebView permissions architecture. Permission requests and geolocation prompts are now strictly validated against the internal secure origin (https://appassets.androidplatform.net). This eliminates arbitrary WebView permission grants and fully complies with the latest Google Play Protect safety standards!
• Native JavaScript-to-Android Interfaces: We added native JS interfaces for critical device features:
  • window.Nitron.requestLocationPermission()
  • window.Nitron.requestCameraPermission()
  • window.Nitron.requestStoragePermission()
• Dynamic Permission Handling: Added robust checkSelfPermission mechanisms before initiating device access requests, preventing unnecessary native dialogs and ensuring a smoother user experience.
• AAB Support for Google Play: You can now build Android App Bundles (.aab) by running npx nitron build --target aab (Note: requires a full JDK to sign the AAB).
• Native Push Notifications: Trigger real Android notifications directly from your web code using window.Nitron.showNotification('Title', 'Message').
• Secure HTTPS Local Origin (appassets.androidplatform.net): We completely removed the deprecated file:// protocol. Your local web files are now served securely via a custom shouldInterceptRequest handler.
• Zero CORS Issues: Absolute paths (/assets/image.png), fetch() requests to external HTTPS APIs, Cookies, and localStorage work flawlessly just like they do on a real browser.
• Micro-Architecture: The entire Android runtime overhead is exactly 9.6 KB (classes.dex). No bloated WebView frameworks.
• New Configuration System (nitron.config.json): Configure Nitron using a pure JSON file. Supports splash screen colors, hardware back-button logic, and cleartext traffic control.
• Dynamic Icons: Don't have an app icon? Nitron automatically provides a sleek glowing neutron default icon at all DPI sizes!
• Framework Presets: Added the --preset flag to nitron init to scaffold configurations for nextjs, vite, react, and vanilla.

🤔 The Problem Nitron Solves

Every 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.

• Capacitor says "web-first" — then asks you to install Android Studio.
• Cordova says "cross-platform" — then requires 8GB of RAM for a build.
• PWAs can't ship on Google Play as real apps.

Nitron makes Android completely invisible — not just simpler. You write HTML, CSS, and JavaScript. You run an npm command. You get a real .apk file in 3 seconds. That's it.

⚡ Quick Start

You can use Nitron globally or locally in your web project.

1. Initialize Nitron

Navigate to your web project (e.g., a Next.js or Vite project) and run:

npx nitron init --preset vanilla

This will generate a nitron.config.json file in your project root.

2. Build your Web App

Compile your framework into static HTML/JS/CSS files (e.g., out/ for Next.js or dist/ for Vite):

npm run build

3. Generate the APK

Run the Nitron build command targeting your output folder:

npx nitron build

Output: dist/app.apk — a real Android APK, ready to install on any device or upload to Google Play!

⚙️ Configuration (nitron.config.json)

Nitron is controlled via a simple nitron.config.json file. Here is a fully detailed example:

{
  "name": "My App",
  "packageId": "com.myname.myapp",
  "version": "1.0.0",
  "entry": "out/index.html",
  "orientation": "portrait",
  "statusBar": true,
  "permissions": ["INTERNET", "ACCESS_NETWORK_STATE", "CAMERA"],
  "icon": "./public/icon.png",
  "network": {
    "cleartext": false
  },
  "webview": {
    "backButton": "history",
    "clearCacheOnStart": false
  },
  "splashScreen": {
    "backgroundColor": "#FFFFFF"
  }
}

Configuration Options

• entry: The path to your compiled entry file (e.g., out/index.html). Nitron will smartly inject the contents of the out directory, keeping paths clean.
• permissions: Nitron v2.0 recognizes over 70+ Android permissions (API 21-34). INTERNET is automatically included.
• icon: Path to a .png or .jpg. Nitron will automatically generate adaptive Android mipmap icons (MDPI to XXXHDPI). If omitted, a default Nitron icon is used.
• webview.backButton: Set to "history" to make the Android hardware back-button trigger browser back navigation.
• network.cleartext: Set to true to allow HTTP traffic. Default is false (HTTPS only).

🗑️ Asset Exclusion (New in v3.1.0)

If you have files in your web project that shouldn't be packaged into your final app bundle (like *.exe tools, backend configurations, or secret files), you can exclude them using the exclude array. Nitron will completely ignore these files during the build, keeping your app ultra-lightweight.

{
  "exclude": ["*.exe", "my-backend-folder", "secret.config"]
}

Glob patterns like *.exe and exact file or folder names are fully supported!

🌐 Framework Compatibility & Best Practices

Nitron seamlessly bundles the output of any web framework. Because v2.0 uses a proper HTTPS-like local origin, modern features work out of the box.

Next.js (Static Export)

Nitron fully supports Next.js Static Exports. Set output: "export" in your next.config.js.

[!WARNING] Next.js Dynamic Routes Warning: Next.js output: "export" strictly prohibits dynamic routes (like /products/[id]/page.tsx) unless you provide a generateStaticParams function. The Nitron Best Practice: Convert your dynamic routes to use Query Parameters (e.g., /products/detail/page.tsx) and read the ID using useSearchParams(). Wrap the component in a React <Suspense> boundary to allow flawless client-side rendering within the APK!

| Feature | Status | Notes | | --- | --- | --- | | Static pages | ✅ | Works perfectly | | Client Components | ✅ | Works perfectly (Wrap useSearchParams in <Suspense>) | | fetch() to external APIs | ✅ | Works perfectly. Make sure your backend CORS allows https://appassets.androidplatform.net! | | Dynamic routes (/[id]) | ⚠️ | Must use Query Parameters (?id=...) instead. | | Server Actions / API Routes | ❌ | No Node.js server at runtime. |

Vite / React / Vue / Svelte

• 100% compatible.
• You no longer need to worry about base: './' configs! Absolute paths from the root (/assets/script.js) resolve correctly because of the HTTPS local origin.

🧠 Under the Hood

How does Nitron v2.0 achieve blazing fast builds without Gradle or Android Studio?

1. The Web-First Runtime

Instead of using the vulnerable setAllowUniversalAccessFromFileURLs(), Nitron ships with a custom shouldInterceptRequest implementation written in pure Java. When the Android WebView requests https://appassets.androidplatform.net/css/style.css, Nitron intercepts this request and reads the file directly from the APK's assets/www/css/style.css in memory. This tricks the WebView into thinking it's browsing a secure remote server, enabling all modern web features. It even has fallback logic to detect .html extensions and handle Single Page Application (SPA) routing!

2. The Build Pipeline

When you run nitron build:

1. No Gradle: Gradle is too slow and heavy. We bypass it entirely.
2. Pre-compiled Template: Nitron uses a highly optimized base.apk template.
3. Asset Injection: We unzip the template, inject your HTML/JS assets into assets/www/, and dynamically modify the AndroidManifest.xml.
4. On-the-fly Compilation: Nitron automatically downloads a tiny, portable version of aapt2 to compile your app's icon and resources instantly.
5. Re-packaging: The modified files are zipped back together and cryptographically signed with a debug keystore using Node.js.

The result? An APK built in under 3 seconds using standard Node.js scripts.

📱 Android Compatibility

| Android | Status | | --- | --- | | Android 5.0 (API 21) | Supported* | | Android 9 (API 28) | Supported | | Android 13 (API 33) | Supported | | Android 14 (API 34) | Supported | | Android 16 (API 36) | Tested & Ready |

*Feature availability may vary by Android/WebView version.

🍎 iOS Compatibility

| iOS | Status | | --- | --- | | iOS 13+ | Supported (shell minimum deployment target) |

Setup required before your first iOS build: see ARCHITECTURE.md for the full walkthrough — in short: scripts/build-ios-toolchain.sh + scripts/build-shell-device.sh (or the equivalent GitHub Actions workflow) build the real-device shell entirely on Linux. No Mac needed for that path, ever. The Simulator target is the one remaining piece that still needs a one-time macOS step.

| Target | Needs | | --- | --- | | --target ios (real device / TestFlight / App Store) | Nothing beyond a one-time Linux toolchain build. Apple Developer account + certificate only for a real (non-ad-hoc) signature. | | --target ios-simulator | A one-time macOS step (iPhoneSimulator SDK isn't available from the same Linux-friendly source as the device SDK). |

🛠️ Requirements

• Node.js 18 or later
• npm (comes with Node.js)
• Java Runtime Environment (JRE) 8+ (for building standard .apk files)
• Java Development Kit (JDK) 8+ (ONLY if you want to build advanced .aab files for Google Play)

That's it for day-to-day nitron build. Building an APK requires zero Android SDK, zero Android Studio, and zero Gradle. Building an IPA requires zero Xcode and zero macOS.

One-time only, to build the iOS shell yourself (§6 of ARCHITECTURE.md) on Linux or WSL2: clang, llvm, lld, cmake, automake, autogen, libtool, libssl-dev, libxml2-dev, uuid-dev, pkg-config, git, xz-utils, zip/unzip. scripts/build-ios-toolchain.sh installs all of these for you via apt-get — you don't need to install them by hand.

🏗️ Contributing & Nitron Development Environment

If you want to contribute to Nitron or modify its core Java template (e.g., adding more Native APIs or customizing the Push Notifications logic), you must set up the full Nitron Development Environment:

1. Install a full Java Development Kit (JDK) 17 or later.
2. Modify the Java code in template-src/.
3. Run node scripts/prepare-template.js to compile your custom MainActivity.java and package it into the template/base.apk.

(Note: Regular users just building web apps into APKs do not need to do this. They receive the template pre-compiled with Push Notifications support out-of-the-box!)

📝 License

MIT © ALightbolt4G