Embed a real Node.js runtime inside your Android app's own process — not a WebView, not a remote service, not a separate binary. Node runs in-process via a JNI bootstrap that calls dlopen("libnode.so") + node::Start, with a bidirectional bridge between JavaScript and Kotlin.
The runtime engine ships as a separate package (aosp-node-runtime), so the bridge and the Node version evolve independently.
- Architecture/design doc:
docs/000-工程规划.md - On-device verification log:
docs/002-真机验证记录.md
| Package | Maven coordinate | Version | Contents |
|---|---|---|---|
| Bridge | io.github.fellow99:node-bridge |
0.2.0 |
Kotlin API, JNI bootstrap (libnode_bridge.so), NAPI addon (libnode_host_client.so), JS payload |
| Runtime | io.github.fellow99:node-runtime |
26.13.0 |
libnode.so + libc++_shared.so only (aosp-node-runtime) |
⚠️ AARCH64 (arm64-v8a) only — no x86 / x86_64 / arm32 artifacts.
| Version | OS | Arch | Link |
|---|---|---|---|
| 0.1.0 | Android | arm64-v8a | https://repo1.maven.org/maven2/io/github/fellow99/node-bridge/0.1.0/ |
| 0.2.0 | Android | arm64-v8a | https://repo1.maven.org/maven2/io/github/fellow99/node-bridge/0.2.0/ |
Requirements: minSdk 24 · arm64-v8a · the engine is loaded at runtime (not compile-time).
// build.gradle.kts
dependencies {
implementation("io.github.fellow99:node-bridge:0.2.0")
runtimeOnly("io.github.fellow99:node-runtime:26.13.0") // engine, Node-version pinned
}// Register host capabilities FIRST, then start (order matters).
val rt = NodeRuntime.getInstance(context)
rt.host.register("fs.pickFolder") { argsJson ->
// Runs on the main thread; return a JSON string.
"""{"ok":true,"path":"/sdcard/Download"}"""
}
val result = rt.start(
NodeRuntimeOptions(
entry = "bootstrap.js", // script node runs directly
appEntry = "selfcheck.js", // business entry resolved by bootstrap
env = mapOf("MY_CONFIG" to "value"),
),
)
if (!result.ok) Log.e("node", "${result.state} ${result.message}") // failures stay visible
// Observe lifecycle state: Idle → Starting → Running → Exited/Failed
rt.state.collect { state -> /* ... */ }Inside Node, call the host:
const host = require('./host.js'); // provided by the library assets
const res = await host.invoke('fs.pickFolder', { title: 'Pick a folder' });
// res === { ok: true, path: '/sdcard/Download' }┌─────────────────────────────── App process ───────────────────────────────┐
│ │
│ Kotlin (NodeRuntime / NodeHostBridge) │
│ ▲ │ host requests (JSON over JNI) │
│ │ result (JSON) ▼ │
│ libnode_bridge.so ◀── slot table ──▶ libnode_host_client.so (NAPI) │
│ ▲ dlopen + dlsym ▲ process.dlopen │
│ │ │ │
│ libnode.so (Node.js + V8, from node-runtime) ◀── bootstrap/host.js │
│ │
└────────────────────────────────────────────────────────────────────────────┘
libnode_bridge.solinks onlylog/dl. It never linkslibnode; it locates the engine withdlopenandnode::Startwithdlsym, so the bridge is decoupled from the Node version.libnode_host_client.sois a NAPI addon. Itsnapi_*symbols are intentionally left undefined (-z undefs) and resolved at runtime against the already-dlopen'dlibnode.so(RTLD_GLOBAL) — guaranteeing Node's own NAPI implementation is used.- JS payload (
bootstrap.js,host.js,selfcheck.js) lives in AARassets, which Android cannotrequiredirectly. The library materializes it intofilesDir/node-bridge(idempotent) before start.
aosp-node-bridge/
├── node-bridge/ # the AAR: Kotlin API + two .so + JS assets
│ └── src/main/
│ ├── cpp/ # node_bridge.c, node_host_client.c, bundled NAPI headers
│ └── java/org/fellow99/nodebridge/
├── payload/ # JS payload (source of truth; copied into AAR assets)
├── samples/minimal-app/ # on-device probe (modern targetSdk 36 / legacy targetSdk 28)
├── tools/ # build-bridge / smoke-host / release-maven / collect-evidence
└── docs/
The bridge builds with the NDK clang directly (no CMake/ninja required for the default path):
# Build the two .so into node-bridge/src/main/jniLibs/arm64-v8a
node tools/build-bridge.mjs
# Host-side gates without a device (JS syntax + bridge JSON contract)
node tools/smoke-host.mjs
# Build the probe APK
gradle :samples:minimal-app:assembleModernDebugNAPI headers are provided via --node-headers <dir> (falls back to the sibling aosp-node-runtime checkout; the stable N-API surface rarely changes across Node majors). The addon is linked against libnode.so (auto-resolved from the node-runtime AAR in the Gradle cache, or via --libnode <path>) so it keeps a DT_NEEDED libnode.so entry — required for the runtime linker to resolve the napi_* symbols on older Android (API 26 verified; see docs/20261106-安卓探针-测试报告.md §二.3 and 2026UAT notes).
| Constraint | Detail |
|---|---|
node::Start is once per process |
A crash/exit is terminal (NodeState.Exited/Failed). A restartable form runs Node in a :node process. |
assets/ is not a filesystem path |
The payload must be materialized to filesDir first (the library does this). |
| JIT must be verified on device | W^X/execmem on modern targetSdk can block V8 JIT. The probe's /facts.jit reports the verdict (JIT and WASM verified working on Android 15). |
| Engine has hard requirements | libnode.so must be ET_DYN, have no PT_INTERP, and export _ZN4node5StartEiPPc. |