Nitron v3.2.0 Released — Native Android Plugins

Turn HTML/CSS/JS into
Real Android & iOS Apps

No Android Studio. No Gradle. No Xcode. Build production signed APK, AAB, and iOS apps in ~2 seconds using only Node.js and a standard Java runtime.

~2.0s
Average Build Time
~214 KB
Ultra-light APK Output
API 21 – 36
Android 5.0 through Android 16
0 MB
Android Studio / Gradle required

Why Developers Choose Nitron

Stop wrestling with multi-gigabyte platform SDKs and fragile Gradle daemons just to render a web page inside a WebView.

Capability / Requirement ⚡ Nitron v3.2.0 Capacitor Cordova PWA
Requires Android Studio? ❌ Never ⚠️ Always required ⚠️ Always required ❌ Never
Requires Gradle Builds? ❌ Zero Gradle ⚠️ Slow Gradle downloads ⚠️ Heavy Gradle builds —
iOS Build without macOS? ✅ Yes (Linux/WSL2 Toolchain) ❌ macOS Only ❌ macOS Only —
Build Duration ~2.0 Seconds 2 – 5 Minutes 3 – 8 Minutes Instant (web only)
Google Play Output (.aab) ✅ Real signed AAB (SDK 36) ✅ Yes ✅ Yes ❌ No (Not a real app)
Output Size ~214 KB ~5 – 15 MB ~6 – 20 MB Web cache
Zero Deprecated File:// URLs ✅ Safe HTTPS Local Origin ✅ Local Server ❌ Insecure file:// ✅ HTTPS

One-Minute Quick Start

Nitron packages the static output of whatever you already use to build your site. Point entry at your built index.html.

For projects with standard HTML, CSS, and JavaScript files:

# 1. Initialize project config
npx nitron init --preset vanilla

# 2. Build your Android APK (test on any device)
npx nitron build

# Output: dist/app.apk (~214 KB) ready in 2 seconds!

Works with Vite's standard build. Absolute paths such as /assets/script.js resolve seamlessly on Nitron's safe HTTPS origin without needing base: './'.

# 1. Initialize Vite preset in your Vite project directory
npx nitron init --preset vite

# 2. Build static assets
npm run build

# 3. Package into native APK
npx nitron build

Next.js is supported through static export. Add output: "export" to your next.config.js.

# 1. Initialize Next.js preset (points entry to "out/index.html")
npx nitron init --preset nextjs

# 2. Build Next.js static export
npm run build

# 3. Build native APK
npx nitron build
⚠️ Dynamic Routes Note
Next.js static export rejects dynamic routes like /products/[id]/page.tsx unless you supply generateStaticParams. For apps, use query parameters instead (/products/detail?id=...) and read it with useSearchParams() inside a <Suspense> boundary.

Build iOS apps using the same config through the initron engine (WKWebView shell):

# Build an unsigned .app for testing in the iOS Simulator (No Apple Developer account needed)
npx nitron build --target ios-simulator

# Build a signed .ipa for real device / TestFlight / App Store (Linux or WSL2, no Mac needed!)
npx nitron build --target ios

Declarative Configuration

Everything lives in nitron.config.json. Pure JSON, no ES Module / CommonJS confusion, and completely CI/CD friendly.

{
  "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",
  "exclude": ["*.exe", "my-backend-folder", "secret.config"],
  "plugins": ["./plugins/BatteryPlugin.java"],
  "onPluginError": "error",
  "network": { "cleartext": false },
  "webview": {
    "backButton": "history",
    "clearCacheOnStart": false,
    "externalLinks": "browser",
    "allowedHosts": ["pay.example.com"]
  },
  "splashScreen": { "backgroundColor": "#0F121D" },
  "android": { "targetSdk": 36, "minSdk": 21 }
}
namestring
The application display name shown on device home screen and launcher.
packageIdstring
Unique reverse-DNS package identifier (e.g. com.company.app). Min 3 segments.
webview.externalLinks'browser' | 'inapp'
New in v3.1.5: Defaults to "browser" to keep third-party links outside the bridge WebView.
webview.allowedHostsstring[]
Hostnames allowed to open inside WebView when externalLinks is 'browser' (e.g. payment/auth gates).
excludestring[]
Glob patterns or exact folder names kept out of the final APK/IPA bundle to reduce bundle size.
pluginsstring[]
Java files or folders compiled into the Android app and exposed through Nitron.plugins.
onPluginError'error' | 'warn'
Stops the build by default when a plugin fails; use "warn" to omit a failing plugin.
android.targetSdknumber
Target Android API level. Defaults to 36 (compliant with newest Google Play mandates).

Built-in Native APIs

Nitron exposes a secure zero-dependency bridge to your client JavaScript as window.Nitron without requiring third-party plugins.

🔔

System Push Notifications

Trigger native Android system notifications directly from your web UI. Automatically requests notification permissions on Android 13+.

// Call from your JavaScript code:
window.Nitron.showNotification(
  'Order Confirmed',
  'Your package is on its way!'
);
📍

Runtime Permissions

Request native device permissions on-demand with built-in checkSelfPermission checks to prevent annoying redundant dialogs.

// Native permission requests:
window.Nitron.requestLocationPermission();
window.Nitron.requestCameraPermission();
window.Nitron.requestStoragePermission();

Native Android Plugins

When the built-in bridge is not enough, write a small Java class and call Android APIs from your web app as promises.

Plugin

Java to Promise API

Extend NitronPlugin, mark a public method with @NitronMethod, then call it from JavaScript. Plugin calls run away from the UI thread and resolve or reject normally.

// JavaScript
const { level, charging } = await
  Nitron.plugins.Battery.getStatus();
Events

Events, Permissions & Lifecycle

Plugins can emit events, request Android permissions, and react to app lifecycle callbacks. Nitron checks plugin code during the build and keeps calls restricted to the app origin.

// Subscribe to an event emitted by Java
Nitron.on('Bluetooth:found', device => {
  console.log(device.name);
});
// nitron.config.json
{
  "plugins": ["./plugins/BatteryPlugin.java"],
  "onPluginError": "error"
}

# Build the Android app (requires a full JDK)
npx nitron build

Plugins are Android-only, support Java source files or folders, and currently allow up to 32 plugins per app. See the full Plugins guide and the ready-made examples.

Defense in Depth Security Model

Nitron is engineered specifically to prevent malicious web exploits and bridge injection vulnerabilities.

🛡️

Safe Local Origin

Local files are served over https://appassets.androidplatform.net via Android's modern shouldInterceptRequest. No insecure file:// URLs or dangerous universal access permissions.

🔒

External Link Isolation

External links load in the system browser by default. This ensures untrusted third-party websites never have access to the native window.Nitron bridge.

🎯

Exact Host Origin Check

In v3.1.5, origin validation performs an exact hostname comparison. Look-alike phishing domains (such as appassets.androidplatform.net.evil.com) are strictly rejected.

Publishing to Google Play Store

Google Play requires an Android App Bundle (.aab) and a persistent release keystore.

🔑

Step 1: Generate Release Keystore

Run once to generate your cryptographic release key. Keep this file safe; you cannot update your app in Google Play without it.

npx nitron keystore
# Generates: nitron-release.keystore
📦

Step 2: Build Signed AAB

Build an optimized, signed Android App Bundle ready to upload directly to the Google Play Console.

npx nitron build --target aab --release
# Generates: dist/app.aab (Play Store compliant)

iOS Support without macOS (initron)

Nitron builds genuine iOS apps using the same nitron.config.json, with a WKWebView shell compiled directly on Linux or WSL2.

How iOS Cross-Compilation Works

Instead of requiring macOS and Xcode, Nitron employs an isolated open-source cross-compilation toolchain based on cctools-port, apple-libtapi, and zsign.

  • Pure Mach-O arm64 Binary: Real native executable generated without Xcode.
  • Standard Payload Structure: Creates Payload/App.app/... directory format accepted by App Store & TestFlight.
  • zsign Code Signing: Signs the application with your Apple Developer Certificate (.p12 + .mobileprovision).

iOS CLI Commands

# 1. Unsigned .app for iOS Simulator:
npx nitron build --target ios-simulator

# 2. Signed .ipa for real iPhone/iPad:
NITRON_IOS_P12_PATH=./cert.p12 \
NITRON_IOS_P12_PASSWORD=secret \
NITRON_IOS_PROVISION_PATH=./profile.mobileprovision \
npx nitron build --target ios

Nitron Dual-Engine Architecture

A decoupled, high-performance architecture separating platform-agnostic core logic from specialized build engines.

Shared Agnostic Core

cli.ts • config.ts • validator.ts • types.ts • pwa.ts • dev.ts

🤖 Nitronoid (Android Engine)

Produces signed APK & AAB packages in under 2 seconds without Gradle.

  1. Unpack: Extracts pre-compiled base.apk template.
  2. Inject Assets: Injects web files into assets/www/.
  3. Compile Resources: Runs lightweight aapt2 for icons and manifest.
  4. Pack & Sign: Packages via jszip and signs with uber-apk-signer.

🍎 Initron (iOS Engine)

Produces Mach-O arm64 IPA & Simulator .app bundles without Xcode.

  1. Unpack Shell: Extracts pre-compiled WKWebView native shell.
  2. Inject Assets: Copies web files into NitronShell.app/www/.
  3. Generate Plist: Patches XML Info.plist with permissions and metadata.
  4. Codesign: Signs with zsign and packages into dist/app.ipa.

Nitron Changelog

Track releases, security fixes, and feature additions.

v3.2.0 (Latest)

Native Android Plugins

  • Native Plugins: Compile Java classes into Android apps and call their @NitronMethod methods with Nitron.plugins.
  • Events & Lifecycle: Plugins can emit web events, request permissions, and react to app lifecycle callbacks.
  • Build Validation: Plugin source is checked for class, constructor, method, duplicate-name, permission, and SDK errors.
  • Plugin Runtime Tests: Run npm run test:plugins to validate the Java dispatcher and generated JavaScript bridge without a device.
v3.1.5

Security Hardening & Toolchain Improvements

  • External Links Default to System Browser: webview.externalLinks defaults to "browser", preventing third-party websites from loading inside the bridge WebView.
  • Exact Hostname Origin Checks: Strict origin validation for bridge calls and geolocation; rejects spoofed hostnames like appassets.androidplatform.net.evil.com.
  • XML Sanitization: Values written to AndroidManifest.xml (app name, splash color) are escaped to prevent XML injection.
  • Auto-downloading Toolchain: scripts/prepare-template.js automatically locates or downloads android.jar and R8 dexer from Google Maven.
  • License Clarification: Formally designated as GPL-2.0-only with the Nitron Output Exception.
v3.1.0 – v3.1.4

Asset Exclusion & SDK 36 Support

  • Asset Exclusion: Added exclude array in nitron.config.json supporting glob patterns (e.g. *.exe).
  • Android 16 Support: Default targetSdk raised to 36 with Play Console warnings.
  • AAB Fixes: R8 mapping and network security fixes for Google Play bundles.
v3.0.0

iOS Engine (initron) & Architecture Restructuring

  • New iOS Engine: Cross-compile native iOS apps from Linux using WKWebView shell.
  • Dual-Engine Architecture: Clear separation between nitronoid (Android) and initron (iOS).
v2.1.0

Native JS Interface & HTTPS Local Origin

  • window.Nitron: Added native JavaScript APIs for Location, Camera, Storage, and Push Notifications.
  • Secure Origin: Migration from file:// to https://appassets.androidplatform.net.
  • AAB Export: Initial support for Google Play App Bundles.

⚖️ License & The Nitron Output Exception

Nitron is licensed under GPL-2.0 with the Nitron Output Exception.

What does the Output Exception mean for you?
You may use Nitron to build applications and distribute the resulting files (APK, AAB, IPA, PWA) under any terms of your choice, including proprietary and commercial closed-source terms. Your code remains 100% yours!

The GPL applies only to modifying and redistributing the Nitron CLI and build tool itself.