Me!

TJ VanToll

Starting NativeScript Apps From Templates

| Comments

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

Or

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

tns-template-tab-navigation

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.

Comments