feat: Allow templates to be full applications

Currently when a project is created the content of the template is placed inside the `app` directory of the newly created project.
This leads to some issues when you want to support more complex scenarios, for example it is difficult to add configuration file (like nsconfig.json or webpack.config.js) in the root of the project.
The suggested solution to allow templates to be the full application is to check the template from which the application is created. In case the template contains a nativescript key and templateVersion property in it, check its value.
In case it is v1, use the old way, i.e. place the content of the template in the app directory of the created project.
In case it is v2 place the content of the template at the root of the application.
In case it is anything else - throw an error.
In case it is missing, use v1 as default.

The solution ensures backwards compatiblity with existing templates and allows creating new types of templates.

Author: rosen-vladimirov

lib/constants.ts

@@ -137,6 +137,7 @@ export const enum DebugTools {
 export const enum TrackActionNames {
 	Build = "Build",
 	CreateProject = "Create project",
+	UsingTemplate = "Using Template",
 	Debug = "Debug",
 	Deploy = "Deploy",
 	LiveSync = "LiveSync",
@@ -145,6 +146,8 @@ export const enum TrackActionNames {
 	CheckEnvironmentRequirements = "Check Environment Requirements"
 }
 
+export const AnalyticsEventLabelDelimiter = "__";
+
 export const enum BuildStates {
 	Clean = "Clean",
 	Incremental = "Incremental"
@@ -189,3 +192,12 @@ export class SubscribeForNewsletterMessages {
 	public static ReviewPrivacyPolicyMsg = `You can review the Progress Software Privacy Policy at \`${PROGRESS_PRIVACY_POLICY_URL}\``;
 	public static PromptMsg = "Input your e-mail address to agree".green + " or " + "leave empty to decline".red.bold + ":";
 }
+
+export class TemplateVersions {
+	public static v1 = "v1";
+	public static v2 = "v2";
+}
+
+export class ProjectTemplateErrors {
+	public static InvalidTemplateVersionStringFormat = "The template '%s' has a NativeScript version '%s' that is not supported. Unable to create project from it.";
+}

lib/definitions/project.d.ts

@@ -201,6 +201,11 @@ interface IImageDefinitionsStructure {
 	android: IImageDefinitionGroup;
 }
 
+interface ITemplateData {
+	templatePath: string;
+	templateVersion: string;
+}
+
 /**
  * Describes working with templates.
  */
@@ -211,9 +216,9 @@ interface IProjectTemplatesService {
 	 * In case templateName is a special word, validated from us (for ex. typescript), resolve the real template name and add it to npm cache.
 	 * In any other cases try to `npm install` the specified templateName to temp directory.
 	 * @param {string} templateName The name of the template.
-	 * @return {string} Path to the directory where extracted template can be found.
+	 * @return {ITemplateData} Data describing the template - location where it is installed and its NativeScript version.
 	 */
-	prepareTemplate(templateName: string, projectDir: string): Promise<string>;
+	prepareTemplate(templateName: string, projectDir: string): Promise<ITemplateData>;
 }
 
 interface IPlatformProjectServiceBase {

lib/services/project-service.ts

@@ -46,8 +46,8 @@ export class ProjectService implements IProjectService {
 		}
 
 		try {
-			const templatePath = await this.$projectTemplatesService.prepareTemplate(selectedTemplate, projectDir);
-			await this.extractTemplate(projectDir, templatePath);
+			const { templatePath, templateVersion } = await this.$projectTemplatesService.prepareTemplate(selectedTemplate, projectDir);
+			await this.extractTemplate(projectDir, templatePath, templateVersion);
 
 			await this.ensureAppResourcesExist(projectDir);
 
@@ -57,17 +57,24 @@ export class ProjectService implements IProjectService {
 				await this.$npmInstallationManager.install(constants.TNS_CORE_MODULES_NAME, projectDir, { dependencyType: "save" });
 			}
 
-			this.mergeProjectAndTemplateProperties(projectDir, templatePackageJsonData); //merging dependencies from template (dev && prod)
-			this.removeMergedDependencies(projectDir, templatePackageJsonData);
+			if (templateVersion === constants.TemplateVersions.v1) {
+				this.mergeProjectAndTemplateProperties(projectDir, templatePackageJsonData); // merging dependencies from template (dev && prod)
+				this.removeMergedDependencies(projectDir, templatePackageJsonData);
+			}
+
+			const templatePackageJson = this.$fs.readJson(path.join(templatePath, constants.PACKAGE_JSON_FILE_NAME));
 
+			// Install devDependencies and execute all scripts:
 			await this.$npm.install(projectDir, projectDir, {
 				disableNpmInstall: false,
 				frameworkPath: null,
 				ignoreScripts: projectOptions.ignoreScripts
 			});
 
-			const templatePackageJson = this.$fs.readJson(path.join(templatePath, "package.json"));
 			await this.$npm.uninstall(templatePackageJson.name, { save: true }, projectDir);
+			if (templateVersion === constants.TemplateVersions.v2) {
+				this.alterPackageJsonData(projectDir, projectId);
+			}
 		} catch (err) {
 			this.$fs.deleteDirectory(projectDir);
 			throw err;
@@ -100,21 +107,32 @@ export class ProjectService implements IProjectService {
 		return null;
 	}
 
-	private async extractTemplate(projectDir: string, realTemplatePath: string): Promise<void> {
+	private async extractTemplate(projectDir: string, realTemplatePath: string, templateVersion: string): Promise<void> {
 		this.$fs.ensureDirectoryExists(projectDir);
 
-		const appDestinationPath = this.$projectData.getAppDirectoryPath(projectDir);
-		this.$fs.createDirectory(appDestinationPath);
+		this.$logger.trace(`Template version is ${templateVersion}`);
+		let destinationDir = "";
+		switch (templateVersion) {
+			case constants.TemplateVersions.v2:
+				destinationDir = projectDir;
+				break;
+			case constants.TemplateVersions.v1:
+			default:
+				const appDestinationPath = this.$projectData.getAppDirectoryPath(projectDir);
+				this.$fs.createDirectory(appDestinationPath);
+				destinationDir = appDestinationPath;
+				break;
+		}
 
-		this.$logger.trace(`Copying application from '${realTemplatePath}' into '${appDestinationPath}'.`);
-		shelljs.cp('-R', path.join(realTemplatePath, "*"), appDestinationPath);
+		this.$logger.trace(`Copying application from '${realTemplatePath}' into '${destinationDir}'.`);
+		shelljs.cp('-R', path.join(realTemplatePath, "*"), destinationDir);
 
 		this.$fs.createDirectory(path.join(projectDir, "platforms"));
 	}
 
 	private async ensureAppResourcesExist(projectDir: string): Promise<void> {
-		const appPath = this.$projectData.getAppDirectoryPath(projectDir),
-			appResourcesDestinationPath = this.$projectData.getAppResourcesDirectoryPath(projectDir);
+		const appPath = this.$projectData.getAppDirectoryPath(projectDir);
+		const appResourcesDestinationPath = this.$projectData.getAppResourcesDirectoryPath(projectDir);
 
 		if (!this.$fs.exists(appResourcesDestinationPath)) {
 			this.$fs.createDirectory(appResourcesDestinationPath);
@@ -128,11 +146,20 @@ export class ProjectService implements IProjectService {
 				ignoreScripts: false
 			});
 
-			const defaultTemplateAppResourcesPath = path.join(projectDir, constants.NODE_MODULES_FOLDER_NAME,
-				defaultTemplateName, constants.APP_RESOURCES_FOLDER_NAME);
+			const obsoleteAppResourcesPath = path.join(projectDir,
+				constants.NODE_MODULES_FOLDER_NAME,
+				defaultTemplateName,
+				constants.APP_RESOURCES_FOLDER_NAME);
+
+			const defaultTemplateAppResourcesPath = path.join(projectDir,
+				constants.NODE_MODULES_FOLDER_NAME,
+				defaultTemplateName,
+				constants.APP_FOLDER_NAME,
+				constants.APP_RESOURCES_FOLDER_NAME);
 
-			if (this.$fs.exists(defaultTemplateAppResourcesPath)) {
-				shelljs.cp('-R', defaultTemplateAppResourcesPath, appPath);
+			const pathToAppResources = this.$fs.exists(defaultTemplateAppResourcesPath) ? defaultTemplateAppResourcesPath : obsoleteAppResourcesPath;
+			if (this.$fs.exists(pathToAppResources)) {
+				shelljs.cp('-R', pathToAppResources, appPath);
 			}
 
 			await this.$npm.uninstall(defaultTemplateName, { save: true }, projectDir);
@@ -188,13 +215,38 @@ export class ProjectService implements IProjectService {
 	private createPackageJson(projectDir: string, projectId: string): void {
 		const projectFilePath = path.join(projectDir, this.$staticConfig.PROJECT_FILE_NAME);
 
-		this.$fs.writeJson(projectFilePath, {
-			"description": "NativeScript Application",
-			"license": "SEE LICENSE IN <your-license-filename>",
-			"readme": "NativeScript Application",
-			"repository": "<fill-your-repository-here>"
-		});
+		this.$fs.writeJson(projectFilePath, this.packageJsonDefaultData);
+
+		this.setAppId(projectDir, projectId);
+	}
+
+	private get packageJsonDefaultData(): IStringDictionary {
+		return {
+			description: "NativeScript Application",
+			license: "SEE LICENSE IN <your-license-filename>",
+			readme: "NativeScript Application",
+			repository: "<fill-your-repository-here>"
+		};
+	}
+
+	private alterPackageJsonData(projectDir: string, projectId: string): void {
+		const projectFilePath = path.join(projectDir, this.$staticConfig.PROJECT_FILE_NAME);
+
+		const packageJsonData = this.$fs.readJson(projectFilePath);
+
+		// Remove the metadata keys from the package.json
+		let updatedPackageJsonData = _.omitBy<any, any>(packageJsonData, (value: any, key: string) => _.startsWith(key, "_"));
+		updatedPackageJsonData = _.merge(updatedPackageJsonData, this.packageJsonDefaultData);
+
+		if (updatedPackageJsonData.nativescript && updatedPackageJsonData.nativescript.templateVersion) {
+			delete updatedPackageJsonData.nativescript.templateVersion;
+		}
+
+		this.$fs.writeJson(projectFilePath, updatedPackageJsonData);
+		this.setAppId(projectDir, projectId);
+	}
 
+	private setAppId(projectDir: string, projectId: string): void {
 		this.$projectDataService.setNSValue(projectDir, "id", projectId);
 	}
 }

lib/services/project-templates-service.ts

@@ -1,40 +1,71 @@
 import * as path from "path";
 import * as temp from "temp";
 import * as constants from "../constants";
+import { format } from "util";
 temp.track();
 
 export class ProjectTemplatesService implements IProjectTemplatesService {
 
 	public constructor(private $analyticsService: IAnalyticsService,
 		private $fs: IFileSystem,
 		private $logger: ILogger,
-		private $npmInstallationManager: INpmInstallationManager) { }
+		private $npmInstallationManager: INpmInstallationManager,
+		private $errors: IErrors) { }
 
-	public async prepareTemplate(originalTemplateName: string, projectDir: string): Promise<string> {
+	public async prepareTemplate(originalTemplateName: string, projectDir: string): Promise<ITemplateData> {
 		// support <reserved_name>@<version> syntax
 		const data = originalTemplateName.split("@"),
 			name = data[0],
 			version = data[1];
 
 		const templateName = constants.RESERVED_TEMPLATE_NAMES[name.toLowerCase()] || name;
 
-		const realTemplatePath = await this.prepareNativeScriptTemplate(templateName, version, projectDir);
+		const templatePath = await this.prepareNativeScriptTemplate(templateName, version, projectDir);
 
 		await this.$analyticsService.track("Template used for project creation", templateName);
 
-		const templateNameToBeTracked = this.getTemplateNameToBeTracked(templateName, realTemplatePath);
+		const templateNameToBeTracked = this.getTemplateNameToBeTracked(templateName, templatePath);
+		const templateVersion = this.getTemplateVersion(templatePath);
 		if (templateNameToBeTracked) {
 			await this.$analyticsService.trackEventActionInGoogleAnalytics({
 				action: constants.TrackActionNames.CreateProject,
 				isForDevice: null,
 				additionalData: templateNameToBeTracked
 			});
+
+			await this.$analyticsService.trackEventActionInGoogleAnalytics({
+				action: constants.TrackActionNames.UsingTemplate,
+				additionalData: `${templateNameToBeTracked}${constants.AnalyticsEventLabelDelimiter}${templateVersion}`
+			});
 		}
 
 		// this removes dependencies from templates so they are not copied to app folder
-		this.$fs.deleteDirectory(path.join(realTemplatePath, constants.NODE_MODULES_FOLDER_NAME));
+		this.$fs.deleteDirectory(path.join(templatePath, constants.NODE_MODULES_FOLDER_NAME));
+
+		return { templatePath, templateVersion };
+	}
+
+	private getTemplateVersion(templatePath: string): string {
+		this.$logger.trace(`Checking the NativeScript version of the template located at ${templatePath}.`);
+		const pathToPackageJson = path.join(templatePath, constants.PACKAGE_JSON_FILE_NAME);
+		if (this.$fs.exists(pathToPackageJson)) {
+			const packageJsonContent = this.$fs.readJson(pathToPackageJson);
+			const templateVersionFromPackageJson: string = packageJsonContent && packageJsonContent.nativescript && packageJsonContent.nativescript.templateVersion;
+
+			if (templateVersionFromPackageJson) {
+				this.$logger.trace(`The template ${templatePath} has version ${templateVersionFromPackageJson}.`);
+
+				if (_.values(constants.TemplateVersions).indexOf(templateVersionFromPackageJson) === -1) {
+					this.$errors.failWithoutHelp(format(constants.ProjectTemplateErrors.InvalidTemplateVersionStringFormat, templatePath, templateVersionFromPackageJson));
+				}
+
+				return templateVersionFromPackageJson;
+			}
+		}
 
-		return realTemplatePath;
+		const defaultVersion = constants.TemplateVersions.v1;
+		this.$logger.trace(`The template ${templatePath} does not specify version or we were unable to find out the version. Using default one ${defaultVersion}`);
+		return defaultVersion;
 	}
 
 	/**