Starting NativeScript Apps From Templates

NativeScript 1.6 shipped with a new --template option for the create command. Let’s look at how it works.

Using existing templates

The easiest way to use the --template option is to point it at an existing NativeScript template up on GitHub or npm. For instance, the “tns-template-blank package” on npm makes it possible to create a completely blank NativeScript app:

tns create my-app-name --template tns-template-blank

Note: tns stands for Telerik NativeScript.

Using official templates

The NativeScript team makes several other templates available in addition to “tns-template-blank”. Here’s the full list.

tns-template-blank

This is the template we already looked it. The template creates a NativeScript app with a minimal starting point.

tns create my-app-name --template tns-template-blank

tns-template-hello-world

This template creates a NativeScript app with a small hello world example in place. This is the default app you get if you run tns create without the --template option.

tns create my-app-name --template tns-template-hello-world

tns-template-hello-world-ts

This template creates a NativeScript app with the same hello world example, however, in this template the example is built with TypeScript.

tns create my-app-name --template tns-template-hello-world-ts

Because TypeScript is commonly used to build NativeScript apps, the NativeScript CLI also provides two shorthands to start with the same hello world TypeScript template.

tns create my-app-name --template typescript

tns create my-app-name --template tsc

tns-template-master-detail

This template creates a NativeScript app with a very basic master-detail UI in place.

tns create my-app-name --template tns-template-master-detail

This template creates a NativeScript app with tab navigation setup.

tns create my-app-name --template tns-template-tab-navigation

tns-template-hello-world-ng

This template creates a NativeScript app with Angular 2 support baked in. At the time of this writing, NativeScript’s Angular 2 support is still in an alpha state; therefore, the NativeScript Angular 2 template is not on npm quite yet. However, the template is on GitHub, and because the --template option supports also supports GitHub-hosted templates, you can use the following command to start a new NativeScript Angular 2 app:

tns create my-app-name --template https://github.com/NativeScript/template-hello-world-ng

Creating your own templates

The official NativeScript templates are great shortcuts for starting your apps, but sometimes you need something a little more custom.

NativeScript templates themselves are essentially nothing more than the app folder of a NativeScript app. For instance, here’s the folder structure of an existing NativeScript app:

.
└── my-app-name
    ├── app
    │   └── ...
    ├── node_modules
    │   └── tns-core-modules
    ├── package.json
    └── platforms
        ├── android
        └── ios

To build a NativeScript template, take all the code out of app, as well as the root package.json file, and place them in a new folder. The template folder structure should look something like this:

.
└── nativescript-template-foo
    ├── App_Resources
    │   └── ...
    ├── main-page.js
    ├── main-page.xml
    ├── ...
    ├── app.css
    ├── app.js
    └── package.json

Tip: The App_Resources folder is optional in a NativeScript template; the NativeScript CLI is smart enough to generate the folder as necessary when you start new apps from a template.

If you get stuck, the NativeScript hello world template on GitHub is a good reference for how to structure a template.

Once you have your template, if you upload the files to GitHub you can immediately use the template with the --template option. For example, this weekend I threw together a small NativeScript drawer template and tossed it up on GitHub. Now, anyone can start a new NativeScript app that uses drawer navigation with the following command:

tns create my-app-name --template https://github.com/tjvantoll/nativescript-template-drawer

Tip: During testing, you can also point the --template option at a local folder—for example tns create my-app-name --template ~/Desktop/my-template.

Even better, because I then published the template to npm, you can use the same template with significantly fewer characters to type:

tns create my-app-name --template nativescript-template-drawer

Note: There’s no official naming convention for NativeScript templates, but I kind of like prefixing my NativeScript templates with “nativescript-template-” for discoverability.

Cool, huh? If you have any questions about templates feel free to ask in the comments. And if you’d like to chat with me and the rest of the NativeScript community about templates, or whatever, join our new fancy Slack channel.

TJ VanToll