Choosing a Module

Choosing a Module

The CLI labels are Native Module, Native JNI Module, and JSI Module. In practical terms, they are a Kotlin/Java module, a Kotlin/Java bridge to C/C++, and a synchronous C++ module.

Decision table

Question	Choose	Reason
Do you need Android services, permissions, content resolvers, or other Android APIs?	Native	Write the implementation in Kotlin or Java.
Do you already have C or C++ code?	JNI, unless a synchronous result is essential	JNI provides a Promise-based API and generated conversion and registration.
Can the operation wait on files, networking, locks, devices, or unpredictable work?	Native or JNI	Do not synchronously block the JavaScript thread.
Must JavaScript receive the result before it can continue?	Consider JSI	Use it only for short operations and a PluginHost version you have tested.
Have you confirmed JSI on the target device and PluginHost?	JSI may be viable	Generation and compilation cannot establish runtime support.

Native: Kotlin or Java

Choose Native for Android APIs or Kotlin/Java libraries. Returned values become JavaScript Promises. Functions returning Unit or void are called without await.

Returning a Promise does not automatically move slow Kotlin or Java work to another thread. Manage long work inside your implementation.

Continue with Kotlin and Java Modules.

JNI: C or C++ behind Kotlin/Java

Choose JNI when you want to write the function in C or C++ and JavaScript can await the result. The generator creates the Kotlin bridge, value conversion, registration, library loading, CMake, and TypeScript declarations.

The generated JNI package does not include a folder for custom Kotlin glue. If you also need Android APIs, use a separate Kotlin/Java module for that work.

Continue with JNI Modules.

JSI: synchronous C++

Choose JSI only when the call must be synchronous and you have verified JSI execution on the target PluginHost. Otherwise, use JNI.

Every JSI export runs on the JavaScript thread. Do not use it for blocking or long-running work, including file access, network access, locks, or large computations.

See JSI Modules for usage and Requirements and Compatibility for the tested runtime evidence.

The generator cannot convert a module between types. If uncertain, start with Native or JNI.