Generating a Local Copy of NativeScript Documentation

This will be a quick post to document how to generate a local copy of the API documentation for NativeScript. One of the things I’ve been disappointed in with the NativeScript ecosystem is the state of the documentation. There are several “How-To” articles and some API documentation on the docs.nativescript.org site but I’ve found a distinct lack of comprehensive documentation to be a stumbling block in learning how to build apps with NativeScript.

In talking with a couple of the Telerik folks in the NativeScript Community Slack team (get an invite if you’re not already on the team), it came out that the team has been working on a way to automatically generate the API documentation using from the source code using an open-source package called TypeDoc. The resulting files haven’t been made publicly available yet as the engineering team is still working on getting the theme and styling modified to suit them.

However, with a little command-line mojo, you can generate your very own, locally-hosted version of the docs. Since NativeScript is open source and hosted on GitHub, you can pull the source down and execute the documentation build yourself.

First, we need to make sure that the Grunt task runner is installed (I’m assuming you already have NodeJS and NPM installed here):

npm install -g grunt

Next we’ll clone the main NativeScript repo:

git clone https://github.com/NativeScript/NativeScript.git

You’ll want to switch to the latest stable tag (after all, you’ll want documentation for the version that gets installed with NPM):

cd nativescript
git checkout v1.7.1

*note: v1.7.1 is the lastest as of this writing. Run `git tag -l` to see what tags exist

One more setup step before we generate the docs. We need to install the dependencies:

npm install

Now that we have the source and all its dependencies, we’re ready to generate the docs:

grunt typedoc

You should see the grunt task kick off and hopefully at the end say “Done, without errors.”
grunt-typedoc-result

If that all went well, you now have a new folder inside your nativescript project folder named `bin`. Look in `/bin/dist/api-ref` and double click the `index.html` or `globals.html` file.

nativescript-folder-structure

Not only can you get your hands on this before the NativeScript team gets it prettified to their liking, but having a local copy is always nice in case you’re like me and sometimes working where there isn’t reliable internet access.

So You Want to Build a Mobile App? (hint: Use NativeScript)

According to some research the number of mobile devices in the world passed the world’s population in late 2014 at somewhere over 7.2 billion devices. While not all of those devices represent a mobile phone in a person’s hand, that number is still staggering and larger today than in was then. Add to that the number of tablets shipped in the last few years and you can see why every company from Amazon to your favorite local restaurant is clamoring for a mobile app to represent their business.

However, building a mobile application that works on multiple platforms has traditionally been very expensive. The two dominant mobile operating systems, Android and iOS, are completely different and require specialized experience in each to build an application. The cost associated with not only maintaining separate development teams, but ensuring that your application provides the same user experience on both platforms can get astronomical. Many businesses just can’t afford that kind of financial commitment.

Enter NativeScript

NativeScript represents a fundamental shift in mobile app development because it allows one code base to be used to build a version of the application for both Android and iOS (with Windows universal apps to be supported soon). If you’ve been around the mobile development space in the past, you’re probably saying to yourself that you’ve heard that siren song before. Likely you are thinking of PhoneGap or Titanium. While the concept of building a cross-platform application from a single code base is not a new one, the approach that NativeScript takes versus these other options is.

NativeScript apps are, well, native. Rather than using traditional web development technologies and packaging them inside a web view container to approximate a native application, NativeScript uses an embedded javascript virtual machine (V8 on Android and JavascriptCore on iOS) to execute your application code and provide access to the native OS APIs. That sounds mind-bending at first, but it boils down to your code being much closer to the “bare metal” of the device and having to go through less “layers” of abstraction to get executed.

Additionally, since NativeScript is accessing native OS APIs, when a new version of the OS is released, you get immediate access to any new features. Let that soak in for a minute — day zero access to new OS features and APIs. You don’t have to wait for someone to write a “wrapper” to a new feature before you can use it in your code (or write a wrapper yourself).

Getting Platform Specific

NativeScript ships with a library of user interface components that render differently depending on what platform the application is running on. Things like buttons, text fields, switches, sliders and more are included to make it easy for your application to look like any other native application running on the same platform. These components are platform-aware and generally simply provide a common, abstracted interface to the underlying platform. Also included are platform-specific attributes that let you further configure their behavior for the platform where your application is currently running.

However, as most developers know, there are times when cross-platform abstractions simply don’t provide what you need in your applications and you must write code that is specific to a particular platform. In those situations, NativeScript allows you to write multiple, platform-specific versions of your components that are dynamically executed based on the OS of the device being used. This allows you to continue to use one code base for your application while being able to tailor the behavior of your application to take full advantage of the capabilities of each platform.

What This Means to the Developer

The bottom line is that if you already know Javascript and HTML, your learning curve to being able to write cross-platform mobile applications is significantly shorter than learning how to develop directly for Android, iOS and/or Windows. No longer do you need to learn up to three entirely new languages and ecosystems. If you have been developing applications with NodeJS, NativeScript will feel even more familiar. NativeScript can use the same RequireJS syntax for dependency injection as you have been used to in NodeJS applications. Add in the ability to leverage nearly any library published to NPM and your development cycle speeds up even more.

If your interest has been stirred, NativeScript has published an excellent Getting Started Guide that you can walk through and experience the magic first-hand. You can also follow me on Twitter or Medium to get notified about upcoming NativeScript articles and tutorials.