Skip to content
Get packs

Guide · Open source

How to use NativeScript: install the CLI, run your first app

Updated · written with AI from the project's own documentation and checked against our catalogue data

NativeScript is an open-source framework that lets you access native iOS and Android APIs directly from JavaScript or TypeScript, so you can build mobile apps that use the platform's own UI and features. This guide is for developers who already work in JavaScript or TypeScript and want native mobile apps without writing separate Swift or Kotlin code for everything. By the end you will know the prerequisites, how to install the NativeScript CLI, how to create and run a project, and where to go next.

NativeScriptNativeScript/NativeScript · ★ 25.7k · MIT

Quick start

  1. 1Install prerequisites. Make sure Node.js and npm are installed on your machine.
  2. 2Install the CLI. Run npm install -g nativescript to install the NativeScript CLI globally.
  3. 3Create a project. Run ns create my-app to generate a new project named my-app.
  4. 4Enter the project folder. Run cd my-app to move into the project directory.
  5. 5Run on Android. Run ns run android to launch the app on an Android emulator or device.
  6. 6Run on iOS. Run ns run ios to launch the app on an iOS emulator or device.

What you need before you start

NativeScript setup relies on Node.js tooling and platform SDKs, so it is best suited to readers with a JavaScript or mobile development background. The README lists Node.js and npm as the prerequisites for installing the CLI.

  • Node.js
  • npm (installed with Node.js)
  • A working knowledge of JavaScript or TypeScript

Install the NativeScript CLI

Install the NativeScript CLI globally with npm. The CLI is the command-line interface used to create, build and run apps.

npm install -g nativescript

Create and open a new project

Use the ns command to create a project, then move into its directory. The README uses my-app as the example name; you can replace it with your own.

ns create my-app cd my-app

Run your app on Android or iOS

From the project directory, run the app on an emulator or device. The README shows Android and iOS as the two run targets in its quick start. Run the command that matches the platform you are testing.

  • Android: run the android target on an emulator or device
  • iOS: run the ios target on an emulator or device
ns run android ns run ios

Choose a UI framework and explore the packages

The README says NativeScript works with Angular, React, Solid, Svelte and Vue, and the project provides starter links for each. It also publishes several @nativescript packages that you will encounter as you build.

@nativescript/core provides primitives for working with iOS and Android APIs, @nativescript/types provides TypeScript types, and @nativescript/webpack contains build utilities and configs used by NativeScript apps.

  • @nativescript/core: primitives for diverse iOS, visionOS and Android APIs
  • @nativescript/types: types for iOS and Android
  • @nativescript/types-minimal: a minimal type set, useful in web-based IDEs
  • @nativescript/webpack: Webpack build utilities and configs

Find plugins and documentation

For tutorials and reference, the README links to the NativeScript documentation and tutorials. Plugins are listed in the project's plugins repository and in the plugin marketplace, which the README describes as a reference for additional plugins. If you need a feature that is not listed in the README, check these sources before committing to the framework.

  • Documentation: docs.nativescript.org
  • Tutorials: docs.nativescript.org/tutorials
  • Plugin marketplace: market.nativescript.org
  • Community: Discord and Stack Overflow (tag nativescript)

What people use it for

  • Building native iOS and Android apps with TypeScript or JavaScript
  • Reusing existing Angular, React, Vue, Svelte or Solid skills for mobile apps
  • Accessing platform APIs directly from JavaScript
  • Building apps for visionOS, according to the README's list of supported runtimes

Frequently asked questions

Is NativeScript free to use?

NativeScript is released under the MIT licence, as shown in the project's README and repository. The copyright notice credits the OpenJS Foundation and NativeScript contributors.

What do I need to install NativeScript?

The README lists Node.js and npm as prerequisites. You then install the CLI globally with npm install -g nativescript.

Can NativeScript build web apps?

No. The README describes NativeScript as focused on native mobile and visionOS runtimes, not browsers. If you only need web apps, it is not the right tool.

Which frameworks does NativeScript support?

The README mentions Angular, React, Vue, Svelte and Solid, and links starter projects for each. It also references Flutter-style and other compatible options only in its general description, so check the docs for details.

How is NativeScript different from React Native or Flutter?

This guide does not compare them in depth. NativeScript's distinctive approach, as the README describes it, is direct access to native iOS and Android APIs from JavaScript. Compare the official docs of each framework against your team's skills and the features you need.

Why does ns run android or ns run ios fail?

The README does not list specific troubleshooting steps. Check that Node.js and npm are installed, that the CLI was installed globally, and that an emulator or device is available for the platform you chose. The NativeScript documentation and Discord community are the README's suggested places for help.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

NativeScript suits JavaScript or TypeScript developers who want native iOS and Android apps and who already use Angular, React, Vue, Svelte or Solid. It is a poor fit for web-only projects, for beginners without JavaScript or mobile experience, or for teams that need features the README does not list.

Install options & downloads