Skip to content

Allow templates to be full application - full support #3798

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
rosen-vladimirov opened this issue Aug 7, 2018 · 0 comments
Closed

Allow templates to be full application - full support #3798

rosen-vladimirov opened this issue Aug 7, 2018 · 0 comments
Assignees
Labels
Milestone

Comments

@rosen-vladimirov
Copy link
Contributor

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:

  1. User executes tns create <name> [--template <some template>]
  2. 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.
  3. CLI creates package.json file at the root of the <name> directory.
  4. CLI sets the application identifier in the "nativescript" key of the newly created package.json
  5. CLI determines the template that have to be installed. If template is not specified, CLI uses the default one - tns-template-hello-world.
  6. 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.
  7. CLI reads the package.json of the specified template. This is done with a package called pacote. It is used inside npm and it gives us the ability to read package.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 the templateVersion property exists in the nativescript key. If it does not exist or its version is v1, CLI uses the steps from project templates v1 (continues from step 7 there). In case the specified templateVersion is not v1, nor v2, CLI fails. In case the version is v2, CLI continues with the steps below.
  8. CLI extracts the content of the template (again by using the pacote package) directly in the newly created project directory (<name>).
  9. CLI modifies package.json (it has been overwritten in step 8.) and removes all metadata keys that npm may have placed. Also CLI removes the templateVersion property from the nativescript key and ensures correct application identifier (id) is set there. CLI also removes all of these keys from the package.json: "name", "version", "displayName", "templateType", "author", "keywords", "homepage", "bugs".
  10. 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 the pacote package to get the App_Resources directory from the latest version of the tns-template-hello-world template.
  11. CLI checks the package.json file of the project for tns-core-modules dependency. This dependency is mandatory for all NativeScript applications. In case the package.json file does not have tns-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 and tns-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 executes npm install --save --save-exact tns-core-modules@<selected version>.
  1. CLI executes npm install at the root of the project. When you execute npm install in a directory where you have package.json file, npm installs both the dependencies and devDependencies specified in this package.json.
    NOTE: npm will install the packages specified in dependencies and devDependencies sections and their dependencies. devDependencies which are not specified directly in the package.json are not installed.
  2. 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 a hooks directory in the template and a after-createProject directory in it. In this after-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:

  1. Placing configuration files in the root of the project, for example firebase.nativescript.json, webpack.config.js, nsconfig.json, etc.
  2. 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.
  3. 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

3 participants