Node-API Android Runtime for NativeScript

NativeScript is an open-source framework for building truly native mobile applications using JavaScript. This repository contains the source code for the Node-API based Android Runtime used by NativeScript.

The Android Runtime is a key component of the NativeScript framework. It is responsible for executing JavaScript code on Android devices. The runtime is built on top of Node-API and provides a way to interact with the Android platform APIs from JavaScript.

The new runtime is based on the Node-API and is designed to be more stable, faster, and easier to maintain. It also supports multiple JavaScript engines, including V8, QuickJS, Hermes, and JavaScriptCore.

• Main Projects
• Helper Projects
• Build Prerequisites
• How to build
• How to run tests
• Misc
• Get Help

Project structure

The repo is structured in the following projects (ordered by dependencies):

• android-metadata-generator - generates metadata necessary for the Android Runtime.
• android-binding-generator - enables Java & Android types to be dynamically created at runtime. Needed by the extend routine.
• android-runtime - contains the core logic behind the NativeScript's Android Runtime. This project contains native C++ code and needs the Android NDK to build properly.
• android-runtime-testapp - this is a vanilla Android Application, which contains the tests for the runtime project.
• napi-implementations - contains the implementation of the Node-API for each supported JS engine.

Helper Projects

• android-static-binding-generator - build tool that generates bindings based on the user's javascript code.
• project-template - this is an empty placeholder Android Application project, used by the NativeScript CLI when building an Android project.

Build Prerequisites

Following are the minimal prerequisites to build the runtime package.

• Install the latest Android Studio.

• From the SDK Manager (Android Studio -> Tools -> Android -> SDK Manager) install the following components:

  • Android API Level 23, 24, 25, 26, 27
  • Android NDK
  • Android Support Repository
  • Download Build Tools
  • CMake
  • LLDB

How to Build

Clone the repo:

git clone https://github.com/NativeScript/napi-android.git

Install the jsparser dependencies:

cd test-app/build-tools/jsparser
npm install

Set the following environment variables:

• JAVA_HOME such that $JAVA_HOME/bin/java points to your Java executable
• ANDROID_HOME pointing to where you have installed the Android SDK
• ANDROID_NDK_HOME pointing to the version of the Android NDK needed for this version of NativeScript

Run command

Windows:

gradlew -Pengine=V8

Mac/Linux:

./gradlew -Pengine=V8

You can pass in QUICKJS, HERMES, JSC or V8 to compile the runtime with the respective JS engine.

• The build process includes building of the runtime package (both optimized and with unstripped v8 symbol table), as well as all supplementary tools used for the android builds: metadata-generator, binding-generator, metadata-generator, static-binding-generator
• The result of the build will be in the dist_[engine] folder. For example if you are building with V8, the result will be in the dist_v8 folder.

How to Run Tests

• Go to subfolder test-app after you built the runtime.

• Start an emulator or connect a device.

• Run command

gradlew runtests

Working with the Runtime in Android Studio

• Open the test-app folder in Android Studio. It represents a valid Android project and you are able to build and run a test application working with the Runtime from the source.

Note: You might need to run the Android Studio from the command line in order to preserve the environment variables. This is in case you get errors like "missing npm" if starting the studio the usual way.

You can change the JS engine used by the runtime by setting the jsEngine property in the build.gradle file in the root of the project. The possible values are QUICKJS, HERMES, JSC or V8.

Contribute

We love PRs! Check out the contributing guidelines. If you want to contribute, but you are not sure where to start - look for issues labeled help wanted.

Get Help

Please, use github issues strictly for reporting bugs or requesting features. For general questions and support, check out Stack Overflow or ask our experts in NativeScript community on Discord.

License

This project is licensed under the Apache License Version 2.0. See the LICENSE file for more info.