Provide a React NativeScript based template through the CLI

[etabakov]

Is your feature request related to a problem? Please describe.
A user should be able to start quickly with a React NativeScript project from the CLI.

Describe the solution you'd like
tns create should be able to use a React NativeScript template to start my project from. The template should be available in the interactive prompt or through the CLI options

Describe alternatives you've considered
An alternative is to start with a React NativeScript template in the Playground, which is also going to be evaluated.

Additional context
The template to be used is proved by @shirakaba in a dedicated repository.

[rosen-vladimirov]

Hey @etabakov , @shirakaba,

I would like to share some information how NativeScript CLI works with --template option and after that I'll share my idea how we can resolve this issue.
CLI has a predefined set of templates that uses when the user does not specify a template to be used. CLI prompts the user and after they select what kind of project they want to create, CLI resolves the selection to a specific template name. For example, in case you want to create a Hello World JavaScript application, no matter if you've selected it from CLI's prompt or you've just executed tns create myApp --js , CLI will try to create application from the template called tns-template-hello-world. The templates are usually consumed from npm, so CLI will try to get the template from there. There's a specific logic for the version of the template that should be used. CLI first searches for the latest version of the template that matches CLI's major.minor version. For example, in case the CLI that you are using is version 6.0.3, it will try to find the latest 6.0.x version of the tns-template-hello-world. In case it finds such, it just uses it. In case not, for example in case there's no 6.0.x versions of the template, CLI will use the latest version from npm. We've implemented this to ensure older CLI versions will not be broken when we publish new minor/major versions. For example in case you are using CLI 6.0 and we publish 6.1 versions of the templates, they'll probably require the new CLI, new runtimes, etc. In case we are just using the latest version of the template, your 6.0 CLI will immediately start using the 6.1 version of the template and there's a huge risk that some things may not work.

So, getting back to the idea of having a React template - I think it is achievable even now. Here's my suggestion:

1. Publish the template in npm. (NOTE: CLI can work with GitHub repos for the --template option, but this will require specific structure of the repo, you lose the ability to use CLI's logic for versioning and also all changes in the repo will be automatically pushed to users).
2. In the documentation of the react-nativescript add the command for creating project: tns create myFirstReactApp --template tns-template-react-nativescipt (or whatever the package name will be).

Regarding publishing the template in npm, I strongly advise you to follow CLI's versioning mechanism, i.e. publish version 6.0.0 now and once NativeScript 6.1 is out, publish a new version - 6.1.0. At least this is our process and it is working great for us. Of course you can publish version 1.0.0 now, but as it does not match CLI's version, CLI will always use the latest version of your template, i.e. once you publish 2.0.0, all CLIs will start using it immediately for project creation.

And one last thing about the template you've created (https://github.com/shirakaba/react-nativescript-starter/blob/ceae8b22d58f31dd02c8f924180e7818abf8847e/mycoolapp/package.json#L3) - in order to make it work with tns create in the same manner as our other templates, you have to add templateVersion: v2 in the nativescript key, as it is done here: https://github.com/NativeScript/nativescript-app-templates/blob/cd37ca406c509f4fcd73d63b2dfe26f91ced2a03/packages/template-hello-world/package.json#L4
More information what does the templateVersion means can be found here: #3542

What do you think for this approach?

[shirakaba]

Hi Rosen, thanks for those instructions. That approach can work fine.

I’m on the phone so can’t investigate easily. I’m not sure exactly which parts of my starter app repo would need to be published to npm (i.e. what files should I include/ignore in the package, and is mycoolapp/package.json located in the correct place for purposes, or do we need a package.json in the level above it?).

Also, at the moment any user’s app is going to be made as “mycoolapp”, with a corresponding app ID, if they use my template. Do I need to change anything in my starter app repo’s package.json to make the name customisable, or is it implicitly handled by the CLI?

Thanks.

[rosen-vladimirov]

Hey @shirakaba ,
Please excuse me for the delayed reply.

During project creation CLI automatically replaces the id from the package.json with a calculated one based on the users input, i.e. when you run:

tns create myApp --template tns-template-react-nativescipt

CLI will use the template and at one of the final steps, it will set the id inside package.json to be org.nativescript.myApp. So you shouldn't worry that your package has id inside the nativescript key of package.json file.

Regarding the files that should be published, the package that will be published in npm must have the content of your mycoolapp directory, i.e. you should pack it only.

At the end of project creation CLI executes a special hook called after-projectCreate - by using it you can add additional logic in your template, for example in case you want to automatically add .gitignore file in the project or print specific message to the user. Note, in the hookArgs you'll find a lot of useful information, like the appId, projectDir, etc. All properties are shown here.
You can find an example how to use the hook here

So, regarding the structure, I would recommend moving all files at the top of your GitHub repository. This will allow users to execute tns create myApp --template https://github.com/shirakaba/react-nativescript-starter/tarball/master and it will create a new app. This could be useful in some cases when you are still working on a new version of the template and some users want to try it.

About the naming of the package, it depends on you - our templates are named tns-template-<type>-<flavor>, for example tns-template-hello-world-angular.
You can name yours tns-template-starter-react, but it really depends on your idea what should be the name.

About the versioning, as I've explained in my previous comment, I strongly recommend you to use the versionning mechanism that we are currently using for our templates, i.e. set your version in the package.json to 6.0.0 (as it currently uses 6.0.x versions of tns-core-modules, tns-android and tns-ios).

Finally, as I'm not sure I've explained everything perfectly, I've prepared a PR (shirakaba/tns-template-blank-react#1) to your template, that you can check. I've tried to explain all changes in the commits, so you can have a better understanding why I've changed something. Hope it helps.

[shirakaba]

@rosen-vladimirov Thank you very much for the PR! The commits are immensely helpful. I'll look over it in detail later – my next two weeks are very busy, but I might have a spare moment at some point in the coming days.

[shirakaba]

@rosen-vladimirov

About the versioning, as I've explained in my previous comment, I strongly recommend you to use the versionning mechanism that we are currently using for our templates, i.e. set your version in the package.json to 6.0.0 (as it currently uses 6.0.x versions of tns-core-modules, tns-android and tns-ios).

If I publish for version 6.1.0 but later find that I need to release a bugfix for my template whilst still targeting tns-core-modules 6.1.0, what version number should I choose? I'm not too familiar with npm versioning conventions.

I hope to sit down with this over the weekend.

[rosen-vladimirov]

Hey @shirakaba ,
In this case you just have to publish 6.1.1 of your template. CLI 6.1.x will use the latest possible 6.1.y version of your template.

[rosen-vladimirov]

@shirakaba you can reference tns-core-modules with ~6.1.0 in your template's package.json file. This way during npm install the latest 6.1.x version of tns-core-modules will be used.
However, in case there's a new version of runtimes, you'll have to release new version of template which will use it: https://github.com/shirakaba/react-nativescript-starter/blob/b59a473dfcca1a8654be9e9b2f92057ef083475c/package.json#L6-L11 - you will have to update the versions here and release 6.1.x of your template.

[shirakaba]

@rosen-vladimirov I've finished making a blank starter, which even supports HMR! Thank you for your patience.

Incidentally, I've renamed the project to tns-template-blank-react, following the pattern of the Vue template (which this imitates). I've also run npm publish on my project. However, I've found that there is a discrepancy.

Creating an app from the repo master ✅

tns create appFromMaster --template https://github.com/shirakaba/tns-template-blank-react/tarball/master
cd appFromMaster
# This works perfectly!
tns run ios

Creating an app from the released package ❌

tns create appFromRelease --template tns-template-blank-react
cd appFromRelease
# This fails to build, as it doesn't copy my webpack.config.js
tns run ios

Can you advise as to why appFromRelease is not copying over my custom webpack.config.js?

[rosen-vladimirov]

Hey @shirakaba ,
The problem is that your npm package does not have the webpack.config.js file included in it. So during npm install, nativescript-dev-webpack places the default webpack.config.js file. In order to fix this, just add the following line in your .npmignore file:

!webpack.config.js

NOTE: this is required because all .js files are excluded in your .npmignore:

[shirakaba]

@rosen-vladimirov

The problem is that your npm package does not have the webpack.config.js file included in it.

Ah, makes sense! I've included that now and republished the template (as v6.1.1), and I can now successfully create an app from it 🥳

Should I do anything to suppress these CLI warnings, or are they unavoidable?

The current project contains a webpack.config.js file located at /Users/jamie/Documents/git/appFromRelease/webpack.config.js that differs from the one in the new version of the nativescript-dev-webpack plugin located at /Users/jamie/Documents/git/appFromRelease/node_modules/nativescript-dev-webpack/templates/webpack.typescript.js. Some of the plugin features may not work as expected until you manually update the webpack.config.js file or automatically update it using "./node_modules/.bin/update-ns-webpack --configs" command.

The current project contains a tsconfig.tns.json file located at /Users/jamie/Documents/git/appFromRelease/tsconfig.tns.json that differs from the one in the new version of the nativescript-dev-webpack plugin located at /Users/jamie/Documents/git/appFromRelease/node_modules/nativescript-dev-webpack/templates/tsconfig.tns.json. Some of the plugin features may not work as expected until you manually update the tsconfig.tns.json file or automatically update it using "./node_modules/.bin/update-ns-webpack --configs" command.

[rosen-vladimirov]

@shirakaba ,
At the moment there's no way to suppress these warnings - they come from the postinstall script of nativescript-dev-webpack package.

I'm glad you managed to create a react-nativescript template. Great work!

[rosen-vladimirov]

Hey @shirakaba ,
I've created a PR in the template that should resolve the mentioned warnings:
shirakaba/tns-template-blank-react#3