Ensure Plugins Quality

NativeScript plugins are the main building blocks for NativeScript applications. These building blocks should work properly installed into applications:

built for Android
built for iOS

Ignoring any of these non-functional requirements could lead to an app that doesn’t work as expected. Throughout this article we'll be referring to the verification of those requirements as 'sanity checks' without writing a single line of test.

Prerequisites

In order to ensure that your plugin runs reliably in any NativeScript application, there are certain prerequisites you may need to complete.

All plugins should have a demo folder that contains a demo application showing how the plugin works. If your plugin is a user interface plugin, and you need to test the plugin in both Angular and non-Angular apps, you should have an additional demo-angular folder containing an Angular app you can test your plugin in. Refer to the article "Supporting Angular in UI Plugins" for more details.

my-plugin
├── demo
├── demo-angular
└── src
     └── package.json

NOTE: It is very handy to have the plugin and demo application(s) in the same repository. The NativeScript official plugin seed defines this structure so if the plugin is based on it, the plugin’s source and the demo app are nicely organized.

In order to ease the process add the following scripts in your package.json file under src folder (the plugins source folder).

"ngc": "node --max-old-space-size=8192 ./node_modules/.bin/ngc"

NOTE In case the ngc command is not found, you need to install it: npm install @angular/compiler-cli --save-dev

This script will initiate Ahead of Time (AOT) compilation. The parameter max-old-space-size is a workaround to fix heap out of memory errors when running node binaries. It's a common issue when using TypeScript 2.1+ and the Angular compiler (ngc). Check out this issue for more information - https://github.com/angular/angular-cli/issues/5618.

NOTE The script above is needed only if the plugin implements some specific Angular wrappers for Angular support.

"build": "npm i && tsc && npm run ngc"

This script will install all NativeScript plugin’s dependencies, compile TypeScript files and initiate Ahead of Time (AOT) compilation.

NOTE The command npm run ngc is needed only if the plugin implements some specific Angular wrappers for Angular support. If this is not the case, it can be removed.

"prepublishOnly": "npm run build"

In the package.json under your demo and demo-angular folders add the following script:

"build.plugin": "cd ../src && npm run build"

This script will be executed before the package is prepared and packed, only on npm publish. More details can be found in the npm-script documentation. This approach is important because it ensures the plugin’s TypeScript is compiled and the plugin’s required metadata is generated every time before publishing.

Refer to the package.json file of the nativescript-facebook plugin where these scripts are also added.

Checking for Readability, Maintainability, and Functionality Errors

TSLint is a great tool for static analysis of your plugin’s code. It will test the plugin for readability and maintainability as well as functionality errors based on customizable rules. A complete list with the available TSLint rules can be found in the tslint repository.

The official NativeScript plugin seed recommends TSLint rules defined in this tslint.json file.

my-plugin
├── demo
├── demo-angular
├── src
|    └── package.json
└── tslint.json

TSLint could be easily incorporated into any NativeScript plugin by following these steps:

Add tslint.json file on root level.
Add the following script in your plugin’s src/package.json file.

"ci.tslint": "npm i && tslint '**/*.ts' --config '../tslint.json' --exclude '**/node_modules/**'"

This script executes the tslint command passing the tslint rules defined in tslint.json file. The installed node_modules will be excluded from the static analysis. Having tslint.json on root level allows using the same TSLint rules for both demo apps by adding the same script.

Now the command npm run ci.tslint will start a static analysis.

Checking in Application Built for Android and iOS

Perhaps the most important sanity checks is whether the demo application consuming the plugin can actually be built. NativeScript supports Android and iOS so both platforms should be covered. The recommendation is to build with latest SDK for Android and iOS.

The NativeScript command for building Android and iOS apps is:

tns build android and tns build ios

Read more details regarding building project with NativeScript CLI.

Automate All Checks with Travis CI

Travis CI is a great way to automate plugin’s sanity checks. It is free for open-source projects. More details can be found in Travis CI documentation. Travis CI will boot a virtual machine and execute commands based on the provided configuration in your .travis.yml file.

First things first! Add an empty .travis.yml file on the root level of your plugin.

my-plugin
├── demo
├── demo-angular
├── src
|    └── package.json
├── tslint.json
└── .travis.yml

NOTE: If you use the NativeScript plugin seed, you have an initial .travis.yml file setup.

This sample uses Build Matrix to initiate several runs as a result of one and Build Stages to separate the execution into stages. The flow will be as follows: 1. Test for Readability, Maintainability and Functionality Errors 2. Build Demo Apps with Your Plugin Installed

Each step starts after successful completion of the previous one. In this way, if there is a functional error, for example, the entire run will be terminated after the fall of the first step and the rest of the steps will not be executed. This behavior is controlled by Build Stages.

According to the Build Lifecycle of each Travis CI build, install is the right phase to install any required dependencies.

Add following commands in the install phase in .travis.yml file:

Install nativescript as a global node module.

- npm install -g nativescript

Configures anonymous usage reporting for the NativeScript CLI. Read more about CLI usage reporting.

- tns usage-reporting disable

Configures anonymous error reporting for the NativeScript CLI. Read more about CLI error reporting.

- tns error-reporting disable

As a result the install phase should be:

install:
    - npm install -g nativescript
    - tns usage-reporting disable
    - tns error-reporting disable

Refer to nativescript-facebook .travis.yml file to see this in reality.

As we mentioned earlier, the plugin should be sanity checked on Android as well as on iOS. The Android specific requirements can be defined in .travis.yml file in android section:

android:
  components:
    - tools
    - platform-tools
    - build-tools-26.0.1
    - android-26
    - android-23
    - extra-android-m2repository

tools and platform-tools components define that the latest revision of Android SDK Tools will be installed. Read more about Travis CI Environment for Android Project.

build-tools-26.0.1 component defines the BuildTools version that will be used.

android-26 component defines the SDK version used to compile the project.

extra-android-m2repository component defines the support library repositories.

Let's add the required stages using the Build Matrix.

Add the following snippet at the beginning of .travis.yml file:

matrix:
  include:

Then add the required stages:

1. Test for Readability, Maintainability and Functionality Errors

- stage: "Lint"
  language: node_js
  os: linux
  node_js: "10"
  script: cd src && npm run ci.tslint && cd ../demo && npm run ci.tslint && cd ../demo-angular && npm run ci.tslint

The machine that is going to be provisioned will be Linux with nodejs v10 installed on it as well as OpenJDK v8. Finally the ci.tslint script will be executed for the plugin's code and for the demo apps.

2. Build Demo Apps with Your Plugin Installed

- stage: "Build"
  env: 
    - BuildAndroid="26"
  language: android
  os: linux
  jdk: openjdk8
  before_install: nvm install 6.10.3
  script: cd demo && npm run ci.android.build && cd ../demo-angular && npm run ci.android.build
- os: osx
  env: 
    - BuildiOS="11"
    - Xcode="9.1"
  osx_image: xcode9.1
  language: node_js 
  node_js: "10"
  jdk: openjdk8
  script: cd demo && npm run ci.ios.build && cd ../demo-angular && npm run ci.ios.build

The scripts (ci.android.build and ci.ios.build) that are executed to build for iOS and Android are located in package.json file of any of the demo apps.

If everything is configured properly, the sanity checks will execute on every code change. The result, and whether the checks pass or not, will look like this:

The main benefit of having sanity checks in place for your NativeScript plugins is that you can develop without spending additional time to ensure your changes don't break existing applications depending on your plugin.

Do not forget to add a Travis CI badge in your NativeScript plugin's project! It reports live status of your CI build and makes your plugin look more reliable.

NativeScript Angular