Get started
Install the latest release on Linux or macOS (it verifies the SHA-256 checksum and installs to ~/.local/bin):
curl -fsSL https://koru.js.org/install.sh | sh
On Windows, use PowerShell, which installs to %LOCALAPPDATA%\Programs\koru:
irm https://koru.js.org/install.ps1 | iex
With Homebrew (macOS, Linux) or Scoop (Windows), using this repository as tap and bucket:
brew tap wux4an/koru https://github.com/wux4an/koru && brew install koru
scoop bucket add koru https://github.com/wux4an/koru; scoop install koru
Set KORU_VERSION=v0.0.1 to pin a version and KORU_INSTALL_DIR to change the folder. You can also download an archive and its .sha256 from the latest release, check it with sha256sum -c koru_0.0.1_linux_amd64.tar.gz.sha256 and gh attestation verify koru_0.0.1_linux_amd64.tar.gz --repo wux4an/koru, or build from source with Go 1.23 or later: go install github.com/wux4an/koru/cmd/koru@latest.
After that, the koru binary is all you need.
koru create my-app # pick a name and a template
cd my-app
koru dev # preview in your browser with live reload
koru run # install and open on a phone or emulator
koru run talks to the adb server that Android Studio or the platform tools run; koru never starts external programs. koru dev --host 0.0.0.0 --qr prints a QR code to open the preview on your phone, and koru logs (or koru run --logs) streams the app's logs and WebView console to your terminal. The first app guide walks through every step.
Keep a secure backup of .koru/signing.pem. koru create and koru init add .koru/ to the project's .gitignore so the key stays out of version control. Android needs the same signing identity for future updates.
Why koru
- One binary, no native toolchain. DEX bytecode, the binary manifest, resources, ZIP and the APK v2 signature are written in Go with its standard library. No Java, Gradle or Android SDK; builds are offline and take milliseconds.
- The loop you know from Capacitor and Expo.
create from a template, dev with live reload, run on a device, build --release to ship.
- The same API in the browser. Under
koru dev, the JavaScript API runs on web implementations, so you can build most of your app before installing it.
- Typed and strict. TypeScript declarations, a JSON Schema for
koru.json, error messages that say how to fix the input, an HTTPS-only app origin and a MessagePort bridge with no addJavascriptInterface.
Need iOS, Google Play bundles or a large plugin ecosystem? See the honest comparison with Capacitor and Expo.
Bring your frontend
Start with koru create my-app --template react (also vue, svelte, vanilla-ts, vite and basic), or add koru to an existing project with koru init and set webDir to the folder containing the generated index.html. Enable spa if your app uses client-side routes. Keep your framework's hot reload with koru dev --proxy http://localhost:5173.
Koru packages static files. Apps that render on a server need a static export or an HTTPS API. Frameworks guide.
Use Android features
The generated app includes a JavaScript module for device information, persistent storage, app information, vibration, sharing, local and scheduled notifications (alarms), opening links in other apps (browser), keeping the screen on (screen) and the clipboard:
import { device, storage, platform } from "/__koru/core.mjs";
const info = await device.getInfo();
await storage.set("theme", "dark");
console.log(platform, info.model); // "android" in the APK, "web" under koru dev
device, storage and app are enabled by default; enable other plugins in koru.json. With a bundler, koru js src/koru writes the module and its types into your sources. See the JavaScript API for arguments, return values and error handling.
Share your app
koru build --release --output app-release.apk
koru verify app-release.apk
A release build disables debugging and uses your existing signing identity. Install and test the release APK before sharing it (koru run --release). To update an app, keep its appId and key, and raise the version with koru bump [patch|minor|major|code] or koru build --bump. koru plugin list|add|remove and koru config edit and inspect koru.json. Distribution guide.
Current support
Koru is in development. APK installation and execution have been tested on an Android 11 (API 30), x86_64 emulator, including local web content, offline use and the standard plugins. The configurable SDK range is 26–36; this does not establish compatibility with every device or API level.
Distribution currently uses APKs for direct installation. AAB output for Google Play is not available. The alarms, browser, screen and clipboard plugins are tested in Chromium and their bytecode is verified, but they have not run on an Android device; alarms are inexact. Linux is the validated operational host; Windows and macOS have compile checks. See the recorded Android results for the tested scope. koru run, koru devices and koru logs are tested against an in-process implementation of the adb server protocol; they are not yet recorded on physical hardware, and the real logcat format is not validated. The framework templates and the orientation, allowBackup, keyboard and deepLinks fields of koru.json (with koru deeplinks for assetlinks.json) have not been run on Android; deep links open the app on its first page and do not pass the URL to JavaScript yet.
Learn more
For work on koru itself, see the test instructions, milestones and documentation website guide. The Android formats and signing core use Go and its standard library; documentation tooling is separate.
License
Original code is MIT licensed. The AOSP JNI header includes its Apache-2.0 license.
