-
-
Notifications
You must be signed in to change notification settings - Fork 197
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.jsonfile 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 insidenpmand it gives us the ability to readpackage.jsonfrom 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 thetemplateVersionproperty exists in thenativescriptkey. 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 specifiedtemplateVersionis 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
pacotepackage) directly in the newly created project directory (<name>). - CLI modifies
package.json(it has been overwritten in step 8.) and removes all metadata keys thatnpmmay have placed. Also CLI removes thetemplateVersionproperty from thenativescriptkey 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_Resourcesdirectory exists. In case it exists, CLI continues with the next steps. In case this directory does not exist, CLI uses thepacotepackage to get theApp_Resourcesdirectory from the latest version of thetns-template-hello-worldtemplate. - CLI checks the
package.jsonfile of the project fortns-core-modulesdependency. This dependency is mandatory for all NativeScript applications. In case the package.json file does not havetns-core-modulespackage as a dependency, CLI does the following:
- CLI finds out the latest matching version of the
tns-core-modulespackage based on CLI's<major>.<minor>.*version. I.e. in case CLI is version 4.1.0 andtns-core-modulespackage 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-modulesas dependency to the newly created project, i.e. it executesnpm install --save --save-exact tns-core-modules@<selected version>.
- CLI executes
npm installat the root of the project. When you executenpm installin a directory where you havepackage.jsonfile,npminstalls both the dependencies and devDependencies specified in this package.json.
NOTE:npmwill install the packages specified independenciesanddevDependenciessections and theirdependencies.devDependencieswhich are not specified directly in the package.json are not installed. - CLI executes
after-createProjecthook. You can use this hook to apply additional modifications to the project. In order to use it, you need to create ahooksdirectory in the template and aafter-createProjectdirectory in it. In thisafter-createProjectdirectory 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.