Node.js for Mobile Apps Cordova plugin

Installation

$ cordova plugin add nodejs-mobile-cordova

Requirements

• Cordova 9.x or higher
• iOS 11 or higher
• Android API 22 or higher

When building an application for the Android platform, make sure you have the Android NDK installed and the environment variable ANDROID_NDK_HOME set, for example:

$ export ANDROID_NDK_HOME=/Users/username/Library/Android/sdk/ndk-bundle

Supported Platforms

• Android (ARMv7a, x86)
• iOS (ARM64)

Reporting Issues

We have a central repo where we manage all the issues related to Node.js for Mobile Apps, including specific issues of the Node.js for Mobile Apps Cordova plugin. So please, open the issue there.

Methods available in the Cordova layer

These methods can be called from the Cordova javascript code directly:

• nodejs.start
• nodejs.startWithScript
• nodejs.channel.on
• nodejs.channel.post
• nodejs.channel.setListener
• nodejs.channel.send

nodejs.channel.setListener(callback) is equivalent to nodejs.channel.on('message',callback) and nodejs.channel.send(msg) is equivalent to nodejs.channel.post('message',msg). They are maintained for backward compatibility purposes.

nodejs.start(scriptFileName, callback [, options])

| Param | Type | | --- | --- | | scriptFileName | string | | callback | function | | options | StartupOptions |

Starts the nodejs-mobile runtime thread with a file inside the nodejs-project directory.

nodejs.startWithScript(scriptBody, callback [, options])

| Param | Type | | --- | --- | | scriptBody | string | | callback | function | | options | StartupOptions |

Starts the nodejs-mobile runtime thread with a script body.

nodejs.channel.on(event, callback)

| Param | Type | | --- | --- | | event | string | | callback | function |

Registers a callback for user-defined events raised from the nodejs-mobile side.

nodejs.channel.post(event, message)

| Param | Type | | --- | --- | | event | string | | message | any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse |

Raises a user-defined event on the nodejs-mobile side.

nodejs.channel.setListener(listenerCallback)

| Param | Type | | --- | --- | | listenerCallback | function |

Registers a callback for 'message' events raised from the nodejs-mobile side. It is an alias for nodejs.channel.on('message', listenerCallback);.

nodejs.channel.send(message)

| Param | Type | | --- | --- | | message | any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse |

Raises a 'message' event on the nodejs-mobile side. It is an alias for nodejs.channel.post('message', message);.

StartupOptions: object

| Name | Type | Default | Description | | --- | --- | --- | --- | | redirectOutputToLogcat | boolean | true | Allows to disable the redirection of the Node stdout/stderr to the Android logcat |

Note: the stdout/stderr redirection is applied to the whole application, the side effect is that some undesired/duplicated output may appear in the logcat. For example, the Chromium console output I/chromium: [INFO:CONSOLE(xx)] is also sent to stderr and will show up in logcat has well, with the NODEJS-MOBILE log tag.

Methods available in the Node layer

The following methods can be called from the Node javascript code through the cordova-bridge module:

  var cordova = require('cordova-bridge');

• cordova.channel.on
• cordova.channel.post
• cordova.channel.send
• cordova.app.on
• cordova.app.datadir

cordova.channel.send(msg) is equivalent to cordova.channel.post('message',msg). It is maintained for backward compatibility purposes.

cordova.channel.on(event, callback)

| Param | Type | | --- | --- | | event | string | | callback | function |

Registers a callback for user-defined events raised from the cordova side.

To receive messages from nodejs.channel.send, use:

  cordova.channel.on('message', listenerCallback);

cordova.channel.post(event, message)

| Param | Type | | --- | --- | | event | string | | message | any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse |

Raises a user-defined event on the cordova side.

cordova.channel.send(message)

| Param | Type | | --- | --- | | message | any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse |

Raises a 'message' event on the cordova side. It is an alias for cordova.channel.post('message', message);.

cordova.app.on(event, callback)

| Param | Type | | --- | --- | | event | string | | callback | function |

Registers callbacks for App events. Currently supports the 'pause' and 'resume' events, which are raised automatically when the app switches to the background/foreground.

cordova.app.on('pause', (pauseLock) => {
  console.log('[node] app paused.');
  pauseLock.release();
});
cordova.app.on('resume', () => {
  console.log('[node] app resumed.');
});

The 'pause' event is raised when the application switches to the background. On iOS, the system will wait for the 'pause' event handlers to return before finally suspending the application. For the purpose of letting the iOS application know when it can safely suspend after going to the background, a pauseLock argument is passed to each 'pause' listener, so that release() can be called on it to signal that listener has finished doing all the work it needed to do. The application will only suspend after all the locks have been released (or iOS forces it to).

cordova.app.on('pause', (pauseLock) => {
  server.close( () => {
    // App will only suspend after the server stops listening for connections and current connections are closed.
    pauseLock.release();
  });
});

Warning : On iOS, the application will eventually be suspended, so the pause event should be used to run the clean up operations as quickly as possible and let the application suspend after that. Make sure to call pauseLock.release() in each 'pause' event listener, or your Application will keep running in the background for as long as iOS will allow it.

cordova.app.datadir()

Returns a writable path used for persistent data storage in the application. Its value corresponds to NSDocumentDirectory on iOS and FilesDir on Android.

Channel callback: function(arg)

| Name | Type | | --- | --- | | arg | any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse |

The messages sent through the channel can be of any type that can be correctly serialized with JSON.stringify on one side and deserialized with JSON.parse on the other side, as it is what the channel does internally. This means that passing JS dates through the channel will convert them to strings and functions will be removed from their containing objects. In line with The JSON Data Interchange Syntax Standard, the channel supports sending messages that are composed of these JS types: Boolean, Number, String, Object, Array.

Notes about other node APIs

os.tmpdir()

On iOS, os.tmpdir() returns a temporary directory, since iOS sets the TMPDIR environment variable of the application to the equivalent of calling NSTemporaryDirectory.

The Android OS doesn't define a temporary directory for the system or application, so the plugin sets the TMPDIR environment variable to the value of the application context's CacheDir value.

Usage

This shows how to build an iOS app that exchanges text messages between the Cordova layer and the Node.js layer. In macOS, using Terminal:

$ cordova create HelloCordova
$ cd HelloCordova
$ cordova platform add ios
$ cordova plugin add nodejs-mobile-cordova
$ cordova plugin add cordova-plugin-console

You can either manually create the ./www/nodejs-project/ folder, the ./www/nodejs-project/main.js file and edit ./www/js/index.js or use the provided helper script to do it automatically. The helper script copies a more extended sample compared to the one provided with the manual steps.

Set up project files using the helper script

If you choose to use the helper script, you will be asked to overwrite the existing ./www/js/index.js file:

$ ./plugins/nodejs-mobile-cordova/install/sample-project/copy-sample-project.sh
$ overwrite www/js/index.js? (y/n [n]) y

The script creates the ./www/nodejs-project/ folder and adds two files:

• ./www/nodejs-project/main.js
• ./www/nodejs-project/package.json

The changes in ./www/js/index.js are needed to invoke Node.js for Mobile Apps from Cordova.

Set up project files using the manual steps

If you want to set up the project manually, first create the project folder for the Node.js files:

$ mkdir www/nodejs-project

Then, with your editor of choice (we use VS Code in this example) create the main.js script file:

$ code www/nodejs-project/main.js

Add the following code to main.js and save the file:

const cordova = require('cordova-bridge');

cordova.channel.on('message', function (msg) {
  console.log('[node] received:', msg);
  cordova.channel.send('Replying to this message: ' + msg);
});

Edit the cordova script file www/js/index.js:

$ code `./www/js/index.js`

Append the following code at the end of the file:

function channelListener(msg) {
    console.log('[cordova] received:' + msg);
}

function startupCallback(err) {
    if (err) {
        console.log(err);
    } else {
        console.log ('Node.js Mobile Engine Started');
        nodejs.channel.send('Hello from Cordova!');
    }
};

function startNodeProject() {
    nodejs.channel.setListener(channelListener);
    nodejs.start('main.js', startupCallback);
    // To disable the stdout/stderr redirection to the Android logcat:
    // nodejs.start('main.js', startupCallback, { redirectOutputToLogcat: false });
};

Search for the onDeviceReady event and in the event handler add a call to startNodeProject():

  onDeviceReady: function() {
      this.receivedEvent('deviceready');
      startNodeProject();
  },

Save the changes to the www/js/index.js file to complete the manual steps of setting up the project files.

After the project files have been created, either manually or using the helper script, open the Cordova app project in Xcode:

$ open platforms/ios/HelloCordova.xcodeproj

Switch to Xcode:

• select HelloCordova to view the project settings
• in the General settings:
  • in the Signing section select a team to sign the app
  • in Deployment Info section select Deployment Target 11.0 or higher

Go back to Terminal to build the Cordova app

$ cordova build ios --device

Switch to Xcode:

• select a target device for the project
• run the project
• enlarge the Console area and scroll to the bottom

If you created the project following the manual steps, the output will look like this:

2017-10-02 18:49:18.606100+0200 HelloCordova[2182:1463518] Node.js Mobile Engine Started
[node] received: Hello from Cordova!
2017-10-02 18:49:18.690132+0200 HelloCordova[2182:1463518] [cordova] received: Replying to this message: Hello from Cordova!

If you used the helper script, the output will look like this:

2018-02-26 09:18:21.178612+0100 HelloCordova[1089:957630] Node.js Mobile Engine started
2018-02-26 09:18:21.385605+0100 HelloCordova[1089:957630] [cordova] MESSAGE from Node: "main.js loaded"
2018-02-26 09:18:21.385760+0100 HelloCordova[1089:957630] [cordova] "STARTED" event received from Node
2018-02-26 09:18:21.385831+0100 HelloCordova[1089:957630] [cordova] "STARTED" event received from Node with a message: "main.js loaded"
[node] MESSAGE received: "Hello from Cordova!"
[node] MYEVENT received with message: "An event from Cordova"
2018-02-26 09:18:21.392035+0100 HelloCordova[1089:957630] [cordova] MESSAGE from Node: "Message received!" - In reply to: "Hello from Cordova!"

Node Modules

Node modules can be added to the project using npm. The Node modules have to be installed in the ./www/nodejs-project/ folder and a package.json file needs to be added to the folder.

If you used the helper script to install the sample project, the package.json file is already present and you can proceed adding the desired Node modules.

If you don't know how to create the package.json file, just copy the sample one from ./plugins/nodejs-mobile-cordova/install/sample-project/www/nodejs-project/package.json. Then proceed with the installation of the Node modules you want to add to your Node.js project:

$ cd www/nodejs-project/
$ npm install module-name

Rebuild your Cordova project so that the newly added Node modules are added to the Cordova application.

On Android, the plugin extracts the project files and the Node modules from the APK assets in order to make them available to the Node.js for Mobile Apps engine. They are extracted from the APK and copied to a working folder (context.getFilesDir().getAbsolutePath() + "/www/nodejs-project/") when the application is launched for the first time or a new version of the application has been installed. Given the project folder will be overwritten after each application update, it should not be used for persistent data storage. To expedite the process of extracting the assets files, instead of parsing the assets hierarchy, a list of files file.list and a list of folders dir.list are created when the application is compiled and then added to the application assets. On Android 6.x and older versions, this allows to work around a serious perfomance bug in the Android assets manager.

Native Modules

On Linux and macOS, there is support for building modules that contain native code.

The plugin automatically detects native modules in ./www/nodejs-project/ by searching for .gypfiles. It's recommended to have the build prerequisites mentioned in nodejs-mobile for Android and iOS. For Android it's also recommended that you set the ANDROID_NDK_HOME environment variable in your system.

Building native modules for Android can take a long time, since it depends on building a standalone NDK toolchain for each required architecture. The resulting .node binaries are then included in the final application in a separate asset path for each architecture and the correct one will be chosen at runtime.

While the plugin tries to detect automatically the presence of native modules, there's a way to override this detection and turn the native modules build process on or off, by creating the www/NODEJS_MOBILE_BUILD_NATIVE_MODULES_VALUE.txt file and setting its contents to 1 or 0 respectively. E.g., from the root path of your project:

echo "1" > www/NODEJS_MOBILE_BUILD_NATIVE_MODULES_VALUE.txt
cordova run android

echo "1" > www/NODEJS_MOBILE_BUILD_NATIVE_MODULES_VALUE.txt
cordova run ios

Troubleshooting

Android

If the installed Android NDK version is >= r18, the following error can occur while building for Android:

FAILURE: Build failed with an exception.

* What went wrong:
A problem occurred configuring root project 'android'.
> No toolchains found in the NDK toolchains folder for ABI with prefix: mips64el-linux-android

This is caused by the Gradle version used by cordova-android version 6.x not supporting the NDK toolchain versions greater than r18, as documented in this cordova-android issue and the Android NDK r18 Changelog's known issues.

The cordova-android issue mentions possible workarounds the user may take to get around this issue, including updating the gradle plugin used by your Android Project / using an older NDK.

To solve this issue while using Android NDK versions >= r18 with cordova-android 6.x without having to update the project created by cordova, the recommended workaround would be to copy the mips64el-linux-android-4.9 and mipsel-linux-android-4.9 toolchains from an older release into your local NDK install or create a local link to other toolchains so that the Gradle internal checks pass, since these toolchains won't be used by Cordova. Here's one way to do this, assuming the ANDROID_NDK_HOME environment variable is set in your system:

cd $ANDROID_NDK_HOME/toolchains
ln -s aarch64-linux-android-4.9 mips64el-linux-android
ln -s arm-linux-androideabi-4.9 mipsel-linux-android

iOS

When using Xcode 10 with cordova-ios version 4.x, the following error might occur when trying to build or run the application:

The executable was signed with invalid entitlements.

The entitlements specified in you Application's Code Signing Entitlements file are invalid, not permitted, or do not match those specified in you provisioning profile.

This is caused by the new Xcode 10 build system, as documented in this cordova-ios issue, including these recommended workarounds:

• Including the --buildFlag="-UseModernBuildSystem=0" flag in the build and run commands:

cordova run ios --buildFlag='-UseModernBuildSystem=0'
cordova build ios --buildFlag='-UseModernBuildSystem=0'

• Adding the flag under the iOS release or debug config when using a build.json config file:

"buildFlag": [
  "-UseModernBuildSystem=0"
]

• Changing the build system to the "Legacy Build System" when building from the Xcode IDE:
  1. In the Xcode "File Menu", select "Project Settings...";
  2. In the "Project Settings..." window, inside the "Per-User Project Settings:" area, change the "Build System:" setting to "Legacy Build System".