The development workflow starts with the NativeScript CLI.
In this article, you’re going to learn the basics of the NativeScript command-line interface, including how to create new apps, how to get those apps running on devices, and how to set up a development workflow that lets you iterate fast.
create
Open your terminal and run the following command to create a new NativeScript application:
ns create
The NS CLI will walk you through selecting a template using interactive prompts.
You can also use the --template
flag with the ns create
command to target a specific template
ns create HelloWorld --template @nativescript/template-hello-world-ts
Here you’re passing two things to the create
command: HelloWorld
which determines the name of the app you are creating, and the --template
option, which tells the NativeScript CLI to scaffold an app using a predefined template named “@nativescript/template-hello-world-ts” found here
For a full list of the templates you can use, see the full list here
The create
command will take a minute to complete, as the NativeScript CLI needs to download a few dependencies while setting up your new app.
clean
This command will clean your NativeScript project. It will delete the node_modules
, hooks
, and platforms
directories from your project. These directories sometime need a clean slate during development of native applications. It is similar to running "Clean Build Folder" in XCode or other IDE environments.
ns clean
If you're having trouble running your application or you have added new dependencies, it's usually a good practice to start with ns clean
before running to be sure you avoid any type of dependency issues or native project build issues.
run
Runs your project on all connected devices or in native emulators for the selected platform. The command will prepare, build and deploy the app when necessary. By default listens for changes in your code, synchronizes those changes and refreshes all selected devices.
ns run android
Launches the app on a connected Android device or Android emulator.
Note
If you get an error at this point you might not have completed the full NativeScript CLI setup.
You must have at least one AVD (Android Virtual Device) configured on your development machine for this command to run your app up on an Android emulator. Or a connected Android device with debugging enabled.
Check the devDependencies
of your package.json
file. @nativescript/android
must be installed to avoid the "Unable to apply changes on device: emulator-5554. Error is: Invalid Version: null." error.
ns run ios
Launches the app on a connected iOS device or iOS simulator.
Note
NativeScript uses Xcode to build and run iOS apps, and Xcode is only available on macOS; therefore, you can only run iOS apps on macOS. There are VM and/or cloud services that allow you to build on a Mac from a PC.
The run
command will take a few seconds to complete, as the CLI will be building and deploying a native Android application. When the command finishes the native emulator will open, and launch your app on the local emulator (or connected device).
You can customize the ns run
command using any of the following options:
--no-hmr
- Disables the webpack HMR option, so changes made during a session will restart the application.--emulator
- Specifies that you want to debug the app in an emulator.--timeout
- Sets the number of seconds that the NativeScript CLI will wait for the debugger to boot. If not set, the default timeout is 90 seconds.--clean
- If set forces rebuilding the native application.Note
If you see this output in the terminal:
Webpack compilation complete. Watching for file changes.
Watchpack Error (watcher): Error: EMFILE: too many open files 'FILE_PATH'
Watchpack Error (watcher): Error: EMFILE: too many open files 'FILE_PATH'
Watchpack Error (watcher): Error: EMFILE: too many open files 'FILE_PATH' <-- This repeats many times
This is related to node configuration options on your machine.
Solution:
Try adding this to your ~/.bash_profile
if you have one or ~/.zshenv
if using Zsh:
export NODE_OPTIONS="--max-old-space-size=6096"
Then open a new terminal window and run your app.
debug
The debug
command builds and deploys a new package on a connected device or emulator. By default, it also starts to track for changes the app
folder, meaning that it will automatically livesync changes in code as soon as they are saved. In order to apply the changes, the CLI will automatically restart the application after each sync.
Note
Changes inside App_Resources
folder (e.g. AndroidManifest.xml
, Info.plist
or any of the resources folders) trigger a rebuild after which live syncing is resumed.
For security reasons, the debugging agent can't be started automatically from the command-line. That's why NativeScript CLI generates a URL which is printed on the screen instead. You need to manually copy it in Google Chrome's address bar to start debugging.
To start the debugger for Android, run the following command:
ns debug android
To start the debugger for iOS, run the following command:
ns debug ios
You can customize the ns debug
command using any of the following options:
--debug-brk
- Prepares, builds and deploys the application package on a device or in an emulator, and stops at the first JavaScript line until either the debugger frontend connects or a 30 seconds timeout elapses.--start
- Attaches the debug tools to a deployed and running app.--emulator
- Specifies that you want to debug the app in an emulator.--timeout
- Sets the number of seconds that the NativeScript CLI will wait for the debugger to boot. If not set, the default timeout is 90 seconds.--no-watch
- If set, changes in your code will not be livesynced.--clean
- If set forces rebuilding the native application.--inspector
- Flag to use the embedded Webkit Web Inspector debugger (default is Chrome DevTools).For more information about Android debugging, run any of the following commands:
ns help debug android
or ns debug android --help
For more information about iOS debugging, run any the following commands:
ns help debug ios
or ns debug ios --help
help
Executing the following command in your terminal will open the CLI's documentation in your web browser.
ns help
To debug NativeScript applications in Visual Studio Code, you need the NativeScript extension for VS Code.
Debugging Android and iOS applications with Chrome by executing ns debug <android | ios>
.
One of the most natural things you can do to debug apps in any environment is writing to the system’s log. In NativeScript logging works a lot as it does on the web, as most of the same console
APIs that work on the web also work in NativeScript.
The console.log()
function is great for outputting primitive values such as strings, numbers, and booleans, but it doesn’t work so well for objects. For those situations you’ll want to use another of the console
object’s methods intended for complex object output: console.dir()
.
To see this in action add a console.log()
in your app code, which uses console.log()
to log a simple object.
export function pageLoaded = () => {
console.log({
type: "Apple",
color: "Red"
});
};
If you look at your console, you’ll see the following not-very-helpful output.
JS: [object Object]
Now replace the console.log
reference with console.dir
. After the NativeScript CLI refreshes your app, you should see the full output of the object in your terminal or command prompt.
JS: === dump(): dumping members ===
JS: {
JS: "type": "Apple",
JS: "color": "Red"
JS: }
JS: === dump(): dumping function and properties names ===
JS: === dump(): finished ===
Apart from using real Android devices, a viable option is to download, install and use an Android emulator. In NativeScript, we can use all Android emulators that are connected and recognized by the ns device
command.
Example output from ns device
$ ns device
Connected devices & emulators
Searching for devices...
┌───┬─────────────────────────┬──────────┬───────────────────┬──────────┬───────────┐
│ # │ Device Name │ Platform │ Device Identifier │ Type │ Status │
│ 1 │ sdk_google_phone_x86_64 │ Android │ emulator-5554 │ Emulator │ Connected │
│ 2 │ bullhead │ Android │ 00d3e1311075c66f │ Device │ Connected │
└───┴─────────────────────────┴──────────┴───────────────────┴──────────┴───────────┘
Tip
Sometimes emulators take longer to start. As a recommendation and to avoid timing issues, start the emulator before executing other CLI commands. Once the emulator is started, leave it open to avoid the initial load time the next time you need to deploy an Android application.
Follow the official documentation on Creating and Managing Virtual Devices, where the process of downloading, setting up, and using Android Emulators via Android Studio is covered.
The avdmanager
is a tool that allows you to create and manage Android Virtual Devices (AVDs) from the command line. The avdmanager
is provided in the Android SDK Tools package (25.3.0 and higher) and is located in <ANDROID_HOME_PATH_HERE>/cmdline-tools/latest/bin/
. For more information about the avdmanager and how to use it to create AVDs, see the official avdmanager documentation.
Command syntax to create new AVD
cd $ANDROID_HOME/cmdline-tools/latest/bin
avdmanager create avd -n name -k "sdk_id" [-c {path|size}] [-f] [-p path]
You must provide a name for the AVD and specify the ID of the SDK package to use for the AVD using sdk_id wrapped in quotes. For example, the following command creates an AVD named test
using the x86 system image for API level 25:
avdmanager create avd -n test -k "system-images;android-25;google_apis;x86"
Note
The above command suggest that the system image is already downloaded. To download an image use the sdkmanager
. For example sdkmanager "system-images;android-25;google_apis;x86"
The following describes the usages for the other options: -c {path|size}: The path to the SD card image for this AVD or the size of a new SD card image to create for this AVD, in KB or MB, denoted with K or M. For example, -c path/to/sdcard/ or -c 1000M. -f: Force creation of the AVD. Use this option if you need to overwrite an existing AVD with a new AVD using the same name. -p path: Path to the location where the directory for this AVD's files will be created. If you do not specify a path, the AVD will be created in ~/.android/avd/.
To list all the downloaded system images use the list
command.
avdmanager list
An applicable option is to use third-party emulators (like GenyMotion). Visit the official sites for details on how to install and use these emulators.
The iOS simulator emulates iOS devices on Macs. The following documentation is a quick way to get the iOS simulator set up. For more information, see Apple's documentation.
On a mac if you have XCode installed with the proper tools, executing ns run ios
from your terminal will launch the Simulator program with a default device. Alternatively, you can open the Simulator program on your mac, select which device(s) you want to open by navigating to File -> Open Simulator
and choosing the device to launch. Then execute ns run ios
and the NativeScript app will launch on the open simulator(s).
Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.
To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".
Let's now set up an Android device to run our NativeScript projects. Go ahead and plug in your device via USB to your development machine.
Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.
adb devices
The device should be listed. See the full adb documentation for troubleshooting and detailed information.
Type the following in your command prompt to install and launch your app on the device:
ns run android
Connect your iOS device to your Mac using a USB to Lightning cable. Navigate to the ios
folder in your project under platforms
, then open the .xcodeproj
file, or if you are using CocoaPods open .xcworkspace
, within it using Xcode.
If this is your first time running an app on your iOS device, you may need to register your device for development. Open the Product menu from Xcode's menubar, then go to Destination. Look for and select your device from the list. Xcode will then register your device for development.
Register for an Apple developer account if you don't have one yet.
Select your project in the Xcode Project Navigator, then select your main target (it should share the same name as your project). Look for the "General" tab. Go to "Signing" and make sure your Apple developer account or team is selected under the Team dropdown. Do the same for the tests target (it ends with Tests, and is below your main target).
If the device is now registered with your developer account you should be able to run your NativeScript app on the device. Execute the following from your terminal to run the app from the CLI:
ns run ios
The app should install and launch on the connected iOS device.
Alternatively, once you have the NativeScript project built, you can open open the native project inside XCode by opening the .xcworkspace
or .xcproject
file from XCode's menu and then running on a connected device or simulator.
Note
Be sure you have prepare/built/run the app at least once before starting the unit test runner.
For more information about end-to-end testing, see @nativescript/detox
plugin.
When you develop new features inside your app, you can ensure that they are working properly and that past functionality has not regressed by writing and executing unit tests on a regular basis. With the NativeScript CLI, you can write and execute unit tests using Jasmine, Mocha with Chai or QUnit.
To run your unit tests, the NativeScript CLI uses Karma.
Before writing and running unit tests, verify that you have completed the following steps.
If you don't have any projects, create a new project and navigate to the directory of the newly created directory.
ns create projectName
cd projectName
If you want to create tests for an existing directory, navigate to the directory of the project.
cd existingProjectDirectory
Note
You don't need to explicitly add the platforms for which you want to test your project. The NativeScript CLI will configure your project when you begin to run your tests.
The NativeScript CLI lets you choose between three widely popular unit testing frameworks: Jasmine, Mocha with Chai and QUnit. You need to configure the project for unit testing by choosing a framework. You can use only one framework at a time.
To initialize your project for unit testing, run the following command and, when prompted, use the keyboard arrows to select the framework that you want to use.
ns test init
This operation applies the following changes to your project.
app/tests
directory. You need to store all tests in this directory. This directory is excluded from release builds.example.js
file in the app/tests
directory. This sample test illustrates the basic syntax for the selected framework.node_modules
.karma.conf.js
in the root of your project. This file contains the default configuration for the Karma server for the selected framework.Note
To enable and write unit tests for TypeScript or Angular project install the TypeScript typings for the selected testing framework.
npm i @types/jasmine --save-dev
npm i @types/mocha --save-dev
npm i @types/qunit --save-dev
With the NativeScript CLI, you can extensively test all JavaScript-related functionality. You cannot test styling and UI which are not applied or created via JavaScript.
When creating tests for a new or existing functionality, keep in mind the following specifics.
app/tests
directory. The NativeScript CLI recognizes JavaScript files stored in app/tests
as unit tests.When creating tests for a new or existing functionality, keep in mind the following limitations.
application.start()
is called.The following samples test the initial value of the counter and the message in the Hello World template. These tests show the specifics and limitations outlined above.
var mainViewModel = require('../main-view-model') //Require the main view model to expose the functionality inside it.
describe('Hello World Sample Test:', function () {
it('Check counter.', function () {
expect(mainViewModel.createViewModel().counter).toEqual(42) //Check if the counter equals 42.
})
it('Check message.', function () {
expect(mainViewModel.createViewModel().message).toBe('42 taps left') //Check if the message is "42 taps left".
})
})
// (Angular w/TypeScript)
// As our intention is to test an Angular component that contains annotations
// we need to include the reflect-metadata dependency.
import 'reflect-metadata'
// A sample Jasmine test
describe('A suite', function () {
it('contains spec with an expectation', function () {
expect(true).toBe(true)
})
})
var mainViewModel = require('../main-view-model') //Require the main view model to expose the functionality inside it.
describe('Hello World Sample Test:', function () {
it('Counter should be 42 on start.', function () {
assert.equal(mainViewModel.createViewModel().counter, 42) //Assert that the counter equals 42.
})
it('Message should be "42 taps left" on start.', function () {
assert.equal(mainViewModel.createViewModel().message, '42 taps left') //Assert that the message is "42 taps left".
})
})
var mainViewModel = require('../main-view-model') //Require the main view model to expose the functionality inside it.
QUnit.test('Hello World Sample Test:', function (assert) {
assert.equal(
mainViewModel.createViewModel().counter,
42,
'Counter, 42; equal succeeds.'
) //Assert that the counter equals 42.
assert.equal(
mainViewModel.createViewModel().message,
'42 taps left',
'Message, 42 taps left; equal succeeds.'
) //Assert that the message is "42 taps left".
})
To use TestBed you have to alter your karma.conf.js
to:
// list of files / patterns to load in the browser
files: [
'src/tests/setup.ts',
'src/tests/**/*.spec.ts'
],
The file src/tests/setup.ts
should look like this for jasmine:
import 'nativescript-angular/zone-js/testing.jasmine'
import { nsTestBedInit } from 'nativescript-angular/testing'
nsTestBedInit()
or if using mocha:
import 'nativescript-angular/zone-js/testing.mocha'
import { nsTestBedInit } from 'nativescript-angular/testing'
nsTestBedInit()
Then you can use it within the spec files, e.g. example.spec.ts
:
import { Component, ElementRef, NgZone, Renderer2 } from '@angular/core';
import { ComponentFixture, async } from '@angular/core/testing';
import { StackLayout } from '@nativescript/core';
import {
nsTestBedAfterEach,
nsTestBedBeforeEach,
nsTestBedRender
} from 'nativescript-angular/testing';
@Component({
template: `
<StackLayout><Label text="Layout"></Label></StackLayout>
`
})
export class ZonedRenderer {
constructor(public elementRef: ElementRef, public renderer: Renderer2) {}
}
describe('Renderer E2E', () => {
beforeEach(nsTestBedBeforeEach([ZonedRenderer]));
afterEach(nsTestBedAfterEach(false));
afterAll(() => {});
it('executes events inside NgZone when listen is called outside NgZone', async(() => {
const eventName = 'someEvent';
const view = new StackLayout();
const eventArg = { eventName, object: view };
const callback = arg => {
expect(arg).toEqual(eventArg);
expect(NgZone.isInAngularZone()).toBeTruthy();
};
nsTestBedRender(ZonedRenderer).then(
(fixture: ComponentFixture<ZonedRenderer>) => {
fixture.ngZone.runOutsideAngular(() => {
fixture.componentInstance.renderer.listen(
view,
eventName,
callback
);
view.notify(eventArg);
});
}
);
}));
});
After you have completed your test suite, you can run it on physical devices or in the native emulators.
Before running your tests, verify that your development machine and your testing devices meet the following prerequisites.
The Android native emulators on which you want to run your tests must be running on your development machine. To verify that your machine recognizes the devices, run the following command.
ns device
The physical devices on which you want to run your tests must be connected to your development machine. To verify that your machine recognizes the devices, run the following command.
ns device
The physical devices on which you want to run your tests must be able to resolve the IP of your development machine. To verify that the device can access the Karma server, connect the device and the development machine to the same Wi-Fi network or establish USB or Bluetooth tethering between the device and the development machine.
Port 9876 must be allowed on your development machine. The Karma server uses this port to communicate with the testing device.
To execute your test suite on any connected Android devices or running Android emulators, run the following command.
ns test android
To execute your test suite on connected iOS devices, run the following command.
ns test ios
To execute your test suite in the iOS Simulator, run the following command.
ns test ios --emulator
To execute your test suite in CI make sure to add --justlaunch
. This parameter will exit the simulator.
ns test ios --emulator --justlaunch
Each execution of ns test
consists of the following steps, performed automatically.
The NativeScript can continuously monitor your code for changes and when such changes occur, it can deploy those changes to your testing devices and re-run your tests.
To enable this behavior, run your ns test
command with the --watch
flag. For example:
ns test android --watch
ns test ios --watch
ns test ios --emulator --watch
The NativeScript CLI remains active and re-runs tests on code change. To unlock the console, press Ctrl+C
to stop the process.
When you configure your project for unit testing, the NativeScript CLI adds karma.conf.js
to the root of your project. This file contains the default configuration of the Karma server, including default port and selected testing framework. You can edit this file to customize your Karma server.
When you modify karma.conf.js
, make sure that your changes meet the specification of the Karma Configuration File.
To integrate the NativeScript unit test runner into a continuous integration process, you need to configure a Karma reporter, for example, the JUnit reporter.
NativeScript plugins are npm packages with some added native functionality. Therefore, finding, installing, and removing NativeScript plugins works a lot like working with npm packages you might use in your Node.js or front-end web development.
The NativeScript team maintains an official marketplace, which displays a filtered list of NativeScript-related plugins from npm. All plugins listed in the marketplace are accompanied by a metadata describing their quality. A search for “accelerometer” on the plugins marketplace will point you at the plugin you need.
Alternatively, since NativeScript plugins are npm packages, you can find NativeScript plugins on npm’s site by searching for “nativescript-plugin-name”. For example, a search of “nativescript accelerometer” would point you right at the NativeScript accelerometer plugin.
If you can't find a plugin, try asking for help on Stack Overflow. The NativeScript team and community may be able to help find what you’re looking for.
Also, make sure to look through the NativeScript core modules, which ship as a dependency of every NativeScript app. There’s a chance that the functionality you need is built in. If you’re still not finding what you need, you can request the plugin as an idea on the NativeScript community forum, or you can take a stab at building the plugin yourself.
Once you’ve found the plugin you need, install the plugin into your app.
For example, the following command installs the NativeScript camera plugin.
npm install @nativescript/camera
Instead of using plugin add
, you can use your package manager as well (npm, yarn, pnpm...):
npm install --save @nativescript/camera
The installation of a NativeScript plugin mimics the installation of an npm package. The NativeScript CLI downloads the plugin from npm and adds the plugin to the node_modules
folder in the root of your project. During this process, the NativeScript CLI adds the plugin to your project’s root package.json
file and also resolves the plugin’s dependencies (if any).
If you need to install a developer dependency in your project (e.g., like @nativescript/types or @nativescript/webpack) then you will need to explicitly save it as a devDependency. To achieve that, use the npm install
command with --save-dev
flag. For example:
npm i @nativescript/types --save-dev
Note
The difference between dependencies and developer dependencies is that dependencies are required to run, while devDependencies are needed only during development. Example for dependency is the @nativescript/camera plugin which is required at runtime so you could use the hardware camera. On the other hand, the @nativescript/types is a developer dependency required only for intelliSense during the development process. The devDependencies
should not be installed as dependencies
to avoid large output build files (large application size). Example package.json
file using both dependencies
and devDependencies
can be found here.
Once the plugin you need is installed, you can start using it in your project. Note that each plugin might have its configuration that needs to be satisfied so always check carefully the plugin's documentation and the README file. The below code snippet demonstrated the basic usage of @nativescript/camera plugin.
import { requestPermissions } from '@nativescript/camera'
requestPermissions()
import { requestPermissions } from '@nativescript/camera'
requestPermissions()
To remove a NativeScript plugin from your project, run the following command from your command line.
ns plugin remove <plugin-name>
For example, the following command removes the NativeScript camera plugin.
ns plugin remove @nativescript/camera
As with installation, the removal of a NativeScript plugin mimics the removal of an npm package.
The NativeScript CLI removes any plugin files from your app’s node_modules
folder in the root of your project. The CLI also removes any of the plugin’s dependencies and also removes the plugin from your project’s root package.json
file.
A package manager is a piece of software that lets you manage the external code, written by you or someone else, that your project needs to work correctly. By default, NativeScript CLI uses Node Package Manager (npm
) for managing the dependencies of the application. When new application is created, CLI automatically calls npm install
to install all of its dependencies.
NativeScript CLI allows you to configure the package manager used when working with dependencies. When you change the default npm
package manager, CLI will use the newly set package manager for all operations it executes related to project dependencies, for example, project creation, managing dependencies, etc.
NativeScript CLI supports three package managers:
npm
- this is the default optionyarn
- you can set it by calling ns package-manager set yarn
. More information about yarn
is available herepnpm
- from version 6.4, you can use pnpm
to manage the dependencies of your application. You can use pnpm
by calling ns package-manager set pnpm
. NOTE: You will have to use --shamefully-hoist
flag if you call pnpm
on your own. CLI passes this flag when installing dependencies with pnpm
and probably your application will not work if you omit it. More information about pnpm
is available here.In case you want to check what is the currently used package manager, you can use:
ns package-manager get
To upgrade a NativeScript application you need to upgrade several things: NativeScript CLI Tooling, the iOS and Android runtimes and the @nativescript/core
module. In the steps below you will see how to do this.
npm install -g nativescript
You should execute the update command in the root folder of your project to upgrade it with the latest versions of iOS/Android runtimes and cross-platform modules.
Note
The update command is introduced in version 2.4 of NativeScript CLI. You should update NativeScript CLI before using this command.
ns update
In order to get the latest development release instead, pass next as argument:
ns update next
You can also switch to specific version by passing it to the command:
ns update 8.0.0
Note
The command ns update
is updating the @nativescript/core
, @nativescript/webpack
, and the runtimes (@nativescript/android
and@nativescript/ios
). The command is combining the next three commands in this article (ns platform add
, npm i --save @nativescript/core
andnpm i @nativescript/webpack --save-dev
).
Important
When using the --configs
flag, any previous configuration will be overwritten and lost. Consider saving any custom code that you have introduced in your webpack.config.js
and reapplying the code after using the --configs
flag.
Follow those steps in order to get the latest versions of Android and/or iOS runtimes. Navigate to the root level folder where your project is, and then if you are working on a Android project, type:
ns platform remove android
ns platform add android
and/or (if you are working on a iOS version on a Mac):
ns platform remove ios
ns platform add ios
The cross-platform modules are available as a npm package named @nativescript/core.
In order to use them in your project, you will have to explicitly install the package, for example (assuming you are still in your main app project folder from the steps above):
npm install @nativescript/core@latest --save
This installs the @nativescript/core package to the node_modules folder and adds it as a dependency to the package.json of the project.
Important
The ns create
command will create a new project, add the @nativescript/core package as a dependency to its package.json and install it. So each new project you create will have the @nativescript/core package installed and you do not have to install it explicitly.
Another place to find @nativescript/core package is NativeScript Releases, where you can find a collection of the available @nativescript/core-*.tgz packages for every release. You can download a selected release and install it by running: npm install <path to @nativescript/core-*.tgz> --save
.
The Angular plugin is available as an npm package named @nativescript/angular. To update the version of the plugin and the related dependency, the package should be explicitly installed, and the related Angular dependencies should be updated accordingly. To ease the update process, the plugin comes with an automated script update-app-ng-deps
located in <project-folder/node_modules/.bin>
folder.
npm i @nativescript/angular@latest --save
./node_modules/.bin/update-app-ng-deps
npm i
title: Running Latest Code description: NativeScript Documentation - Running Latest Code position: 40 slug: latest-code previous_url: /running-latest
Often when working with open-source projects, one needs functionality that has not yet passed the full release cycle, or even functionality that is not yet fully implemented. We know that many of you are experimenters and want to try the latest and greatest features of NativeScript. That is why we tried to make this process simple and easy to follow. There are two ways to get the latest development code for NativeScript:
As an open-source project NativeScript keeps not only its source code but its build infrastructure open. That is why we choose Travis CI for our nightly builds. Every commit in the master branch of all major NativeScript repos triggers a Travis CI build which publishes an npm package that can be used directly. Follow those simple steps to get the latest development version of NativeScript:
npm uninstall -g nativescript
npm install -g nativescript@next
next
:{
"description": "NativeScript Application",
"dependencies": {
"@nativescript/core": "next"
},
"devDependencies": {
"@nativescript/android": "next",
"@nativescript/ios": "next"
}
}
Instead of editing the package.json file by hand, you could run the following commands:
ns platform add ios@next
ns platform add android@next
npm install @nativescript/core@next
npm install
command to update the node modules:cd <your-project-folder>
npm install
You are now ready to use the latest development version of NativeScript.
Building the source code is essential when one wants to contribute to an open source project. The statement is applicable for NativeScript as well. According to the Contribution Guidelines, suggesting a fix involves testing the latest code.
npm install nativescript -g
: Node Package Manager (npm) downloads and installs the NativeScript CLI.ns create [AppName]
: The NativeScript CLI downloads the Hello-World template and unpacks it to a folder named after the app name you choose. At the same time, the CLI installs the NativeScript cross-platform modules. As a result, your application folder now contains an app
folder, holding the files of your application (source code) and a node_modules
folder, having the cross-platform modules (source code).ns platform add android/ios
: The NativeScript CLI downloads the latest SemVer-compatible version of the specified runtime, unpacks it and applies transformations to the native (Android Studio or xCode) project (e.g., changes the project name).ns run android/ios
: The NativeScript CLI copies the files under the app
folder to the platforms/[android/ios]/.../app
folder following a specific logic so that these get used later by a native build tool (gradle/xcode-build). As a next step, the NativeScript CLI executes compilation, deployment and run commands of gradle or xcode-build.The NativeScript framework is built using TypeScript. For that, one of the build steps is TypeScript compilation, which uses TypeScript declarations of the underlying native objects. These are really large files (android17.d.ts and ios.d.ts). The TypeScript compilation with these two files loaded in memory takes a lot of time. To save development time and have as quick and stable feature output, the NativeScript team decided to keep several important applications inside the same repository so that all of them get compiled in a single pass.
Having said that, each subfolder of the apps subfolder of the repo represents a single application.
When the repo gets built, it outputs a bunch of packages (stripping the version- and extension- part of the filename for clarity):
The repo gets built via the commands:
npm install -g grunt-cli
npm install
grunt
To use the latest:
@nativescript/core
folder from the node_modules
subfolder of your project (i.e., rm -rf node_modules/@nativescript/core
for Linux or rd /S /Q node_modules\@nativescript/core
).npm install [PATH-TO-NATIVESCRIPT-REPO/bin/dist/nativescript-core-x.x.x.tgz]
).It is possible that an internal breaking change gets introduced involving an update to both the runtimes and the modules. An internal breaking change would mean that the public API of the tns_modules does not get affected, but a work in progress change in the runtimes requires a change in the internal code of the tns_modules themselves.
When such a case happens, the ios and android runtimes must be built separately and updated via the CLI command of: ns platform update android/ios --frameworkPath=[Path-to-Runtime-Package]
As the NativeScript framework gets distributed via npm, the runtimes are also packed as npm packages. For consistency reasons, the native builds (gradle/xcode-build) are wrapped by grunt builds that do the job.
The android runtime depends on the android-metadata-generator.
Provided you have all the dependencies set, the easiest way to have the Android runtime built is to clone the two repos to a single folder so that the two are sibling folders, cd
into the android-runtime
folder and run:
gradle packar -PwidgetsPath=./widgets.jar
The resulting @nativescript/android-x.x.x.tgz package will get created in the dist
folder.
Follow the instructions on setting up the dependencies for building the ios runtime in the repository README and then run grunt package
.
The build @nativescript/ios-x.x.x.tgx package will get created in the dist
folder.
You can develop NativeScript apps in any text editor or IDE you prefer.
Most of the NativeScript team prefers to use VS Code from Microsoft as their editor for NativeScript apps. Some reasons we use VS Code:
If you do choose to try Visual Studio Code, let’s look at one tip you might find useful as you develop NativeScript apps.
code
commandAfter you install Visual Studio Code, you can open projects using the editor’s File
→ Open
menu option, but there’s an alternative option that works far better for command-line-based projects like NativeScript: the code
command.
The code
command runs in your command-line or terminal, and it works just like the ns
command does for NativeScript apps. Visual Studio Code installs the code
command by default on Windows on Linux, but on macOS, there’s one manual step you must perform.
Once set up, you can type code .
in your terminal to open the files in your current folder for editing. For example, you could use the following sequence of command to create a new NativeScript app and open it for editing.
ns create MyNewApp
cd MyNewApp
code .
If you’re a WebStorm user, check out this popular community-written plugin that adds many NativeScript-related features.