Description
Continuation of #3636
With 4.1.1, CLI allows using any application as a template. The only change you must apply is to add "templateVersion": "v2"
inside nativescript key of the package.json:
{
"name": "new-template-name",
"version": "4.0.0",
"nativescript": {
"templateVersion": "v2"
}
}
This approach allows you to predefine the versions of runtimes that will be used with this template, to add all configuration files, like nsconfig.json
, firebase.config.json
, directly in the project.
The workflow of project creation when template v2 is used is:
- User executes
tns create <name> [--template <some template>]
- CLI checks if directory called
<name>
exists. If yes and it is not empty, command fails. If the dir is empty or it does not exist, CLI creates the directory and uses it for project dir. - CLI creates
package.json
file at the root of the<name>
directory. - CLI sets the application identifier in the "nativescript" key of the newly created package.json
- CLI determines the template that have to be installed. If template is not specified, CLI uses the default one - tns-template-hello-world.
- CLI determines which version of the template to install. This is done by listing all versions of the specified template and using the latest version matching CLI's
<major>.<minor>.*
version. So, in case CLI is version 4.1.3 and the specified template has versions 1.0.0, 2.0.0, 3.0.0, 4.0.0, 4.1.0, 4.2.0, CLI will use 4.1.0. In case the template has 4.1.1, 4.1.2, 4.1.3, CLI will use 4.1.3. In case no matching version is found, CLI uses the latest available version. - CLI reads the package.json of the specified template. This is done with a package called
pacote
. It is used insidenpm
and it gives us the ability to readpackage.json
from packages that can be npm installed, i.e. packages from npm, GitHub repositories, local directories, .tgz files. In the read package.json, CLI checks if thetemplateVersion
property exists in thenativescript
key. If it does not exist or its version isv1
, CLI uses the steps from project templates v1 (continues from step 7 there). In case the specifiedtemplateVersion
is not v1, nor v2, CLI fails. In case the version isv2
, CLI continues with the steps below. - CLI extracts the content of the template (again by using the
pacote
package) directly in the newly created project directory (<name>
). - CLI modifies
package.json
(it has been overwritten in step 8.) and removes all metadata keys thatnpm
may have placed. Also CLI removes thetemplateVersion
property from thenativescript
key and ensures correct application identifier (id
) is set there. CLI also removes all of these keys from thepackage.json
: "name", "version", "displayName", "templateType", "author", "keywords", "homepage", "bugs". - CLI checks if the project has required App_Resources, i.e. if the
<name>/app/App_Resources
directory exists. In case it exists, CLI continues with the next steps. In case this directory does not exist, CLI uses thepacote
package to get theApp_Resources
directory from the latest version of thetns-template-hello-world
template. - CLI checks the
package.json
file of the project fortns-core-modules
dependency. This dependency is mandatory for all NativeScript applications. In case the package.json file does not havetns-core-modules
package as a dependency, CLI does the following:
- CLI finds out the latest matching version of the
tns-core-modules
package based on CLI's<major>.<minor>.*
version. I.e. in case CLI is version 4.1.0 andtns-core-modules
package has versions 4.0.0, 4.1.0, 4.1.1, 4.1.2, 4.2.0, CLI will select the 4.1.2 version. - CLI installs the selected version of
tns-core-modules
as dependency to the newly created project, i.e. it executesnpm install --save --save-exact tns-core-modules@<selected version>
.
- CLI executes
npm install
at the root of the project. When you executenpm install
in a directory where you havepackage.json
file,npm
installs both the dependencies and devDependencies specified in this package.json.
NOTE:npm
will install the packages specified independencies
anddevDependencies
sections and theirdependencies
.devDependencies
which are not specified directly in the package.json are not installed. - CLI executes
after-createProject
hook. You can use this hook to apply additional modifications to the project. In order to use it, you need to create ahooks
directory in the template and aafter-createProject
directory in it. In thisafter-createProject
directory you can create as many .js files as you want and CLI will execute them all when executing the hook.
And voila, the project is created.
The new approach allows:
- Placing configuration files in the root of the project, for example firebase.nativescript.json, webpack.config.js, nsconfig.json, etc.
- Locking the versions of the runtimes for this template. With v1 the templates cannot specify versions of the runtime with which they work. With v2 you can specify the exact versions.
- Speed-up - fewer npm installs lead to much better time for project creation.
IMPORTANT: Templates with version v2 are never
npm installed
, i.e. CLI will never execute their npm scripts (preinstall, postinstall, etc.). This is by design for faster project creation. In case you want to execute any operation after project is created, use the after-createProject hook.