getting-started-developers.md

Getting started developers

To contribute to Web Template Studio.

If you are authoring templates for Web Template Studio, or interested in contributing to this repo, then you are likely interested in how to use the latest version of this code.

This document covers:

• Prerequisites
• Project folder structure
• Core Template Studio Submodule
• How to run the extension locally
• How to develop the client
• Troubleshooting
• How to build a local vsix
• Tests
• Under the hood
• Folder overview

Before starting make sure you read the Web Template Studio arquitecture document.

If you just want to take advantage from Web Template Studio extension, check the Web Template Studio Installation Instructions page.

Prerequisites

For a full-stack web application

1. Install Node.js
2. Install Gulp
3. Install Git
4. Install .NET Core SDK
5. Install Visual Studio Code
6. Install Yarn. You will need to finish installing Node.js before you install Yarn.
7. Run the command npm config set scripts-prepend-node-path true. This tells VSCode which Node version to run during the extension compilation (otherwise you'll get an error during the build process).

For a react native application

You have to check the following [dependencies](https://microsoft.github.io/react-native-windows/docs/rnw-dependencies).

In the Wizard you have a link on the right-side bar, to show a modal with the System Requirements. If any of them is missing you will see a warning.

If you are running `WebTS` in Mac/Linux you will see a different message, notifying you that the generated native Windows application cannot be run.

<img alt="React Native System Requirements" src="../resources/react-native-requirements.png" width="85%" />

Note: When developing in WebTS you may also need to install React-scripts and Typescript.

Project folder structure

src folder

This folder contains the source code for the different components of Web Template Studio.

• client: This folder contains the client or wizard code.

  • src:
    • assets: contains all the SVGs used for the frontend.
    • components: contains all React components that are reusable.
    • css: CSS contains styling that is global.
    • mockData: mocked data to be able to use from the browser while developing.
    • modals: React components and their subcomponents are displayed as modals.
    • pages: React components and their subcomponents are displayed as main pages on the Wizard.
    • store: contains reducers, actions, interfaces, and selectors for the Redux store.
    • utils: contains helper functions, constants, and others. For example: validation, routes, and extensionService.
      • extensionService: allows client-extension communication.

• extension: This folder contains the Visual Studio extensions code.

  • src:
    • azure: contains all functionality related to azure services.
    • client-modules: contains the client-modules that allow client-extension communication.
    • telemetry: contains all functionality related to telemetry.
    • utils: contains helper functions as logger and validators.

• CoreTemplateStudio: This solution contains the Core Template Studio code.

For more information on internal structure, see Core Template Studio docs.

_build folder

This folder contains scripts for local development and usage from the build pipeline.

dist folder

This folder will contain the .vsix if generated.

templates folder

This folder contains the templates that are used to generate the code. For more info on templates see Understanding the Templates.

template-test folder

This folder will contain all the combination of possible generated applications when running the script "template-tests" existing on the extension.

Core Template Studio Submodule

Web Template Studio relies on Core Template Studio for template synchronization and template composition, generation and postaction. Core Template Studio has its own Github repository as it is shared with the sibling project Windows Template Studio.

Core Template Studio is integrated into Web Template Studio using a git submodule under the folder /src/CoreTemplateStudio. The submodule points to a specific commit in Core Template Studio, that you can see in github:

Init /update

When you clone Web Template Studio you have to run two commands: git submodule init and git submodule update to fetch all the data from Core Template Studio. When fetching changes, also execute git submodule update after doing git fetch to be sure you're submodule is up to date.

Update with remote changes

Changes on Core Template Studio should be done on the Core Template Studio repos. In WebTS, to update the submodule to the most recent commit, you have to run the command: git submodule update --remote.

This will require a new git submodule update on other local repositories to get the update.

For more info visit the official documentation.

How to run the extension locally

1. Run ./build-all.sh from the _build folder. This script installs dependencies and compiles the client and core template studio and copies it to the extension. It also builds and installs the extension.

   There are also separate scripts:

   • For building the client (build-client.sh).
   • For the Core Template Studio Cli (build-coretscli.sh).
   • For the extension (build-extension.sh).

2. Open the src/extension folder using VSCode.

3. Start the debugger by pressing F5. This should open the Extension Development Host in a new Visual Studio Code window.

4. In the Extension Development Host, press Ctrl + Shift ⇧ + P in Windows/Linux or Command ⌘ + Shift ⇧ + P in Mac to open the Command Palette.

5. In the Command Palette, type Web Template Studio (local): [create command name] and press Enter to launch the extension.

   Note: There´s concurrent installation support, so you can run multiple versions of the extension on the same vscode instance.

   • Web Template Studio: [create command name]: this would launch the marketplace version.
   • Web Template Studio (local): [create command name]: this would launch the local version of the extension while developing.
   • Web Template Studio (nightly): [create command name]: this would launch an installed instance of the extension.

   You can check available commands here.

How to develop the client

As the client is injected as a static web app in the webview of the extension, debugging inside the extension can be challenging. Running the client in a browser is useful for quickly testing HTML or CSS changes and for debugging since you can use Chrome extensions such as React and Redux developer tools.

When running in the browser, communication with the extension is done against the mock mockVsCodeApi.ts in the mockData folder. Note that the behaviour of the client on the browser may differ from the behaviour in the extension, so make sure to test out both.

Styles are mocked in the Browser using the file mockThemes.css.

To choose what platform you want to debug, you can modify mockConfig.ts in the mockDatafolder.

1. Run ./build-client.sh from the _build folder. Or you can use the command yarn build if you are on the client folder already.
2. Open the src/client folder using VSCode.
3. Start the client using yarn start to begin development in the browser. We recommend using a chromium based browser such as Chrome.

More info:

• React Developer Tools
• Redux Developer Tools

To debug from Visual Studio Code:

Install Debugger for Chrome extension in Visual Studio Code debug Wizard Client. After starting the client using yarn start in VSCode Debug View (Ctrl + Shift ⇧ + D (Windows/Linux) or Shift ⇧ + Command ⌘ + D (Mac) in Visual Studio Code) select "Debug WebTS Client" and start debugging (you can directly press: F5).

More info:

• Debugger for Chrome
• Debugging in Visual Studio Code

How to build a local vsix

Run ./createLocalVsix.sh from the _build folder.

The script will compile the client, CoreTS (in release mode) and the extension and package the extension into the root directory /dist folder. The vsix package can be distributed and installed by anyone who has VSCode using the command in the extension directory:

code --install-extension [extensionName].vsix

webts-0.0.0-UNTRACKEDVERSION.vsix is the default extensionName.

Alternatively, the extension can be installed from the context menu of the extension section in Visual Studio code using the "install from VSIX..." command. The installed vsix package can be found in the extensions folder. For Windows, it is %USERPROFILE%\.vscode\extensions. For Mac/Linux, it is ~/.vscode/extensions (By Default).

After installation, use Ctrl + Shift ⇧ + P (Windows/Linux) or Command ⌘ + Shift ⇧ + P (Mac) in Visual Studio Code to open the Extension Launcher and select Web Template Studio: [command name] to run the extension.

You can check available commands here.

Possible problems and workarounds to fix them

You may get some errors on the output console for the extension: webtemplatestudio-{env}, or maybe you realise that there´s missing information displayed on the screen. For example, no Frameworks at all for the Create Web App command. Make sure you have the proper versions of the .mstx for the templates in the extension folder - as mentioned above, for Windows would be %USERPROFILE%\.vscode\extensions\wasteamaccount.webtemplatestudio-{environment}-{version}\src\corets-cli or in Mac/Linux ~/.vscode/extensions/wasteamaccount.webtemplatestudio-{environment}-{version}/src/corets-cli.

If that´s not the case, and you have an older version, or you´re missing some package of templates, then you will need to retrieve them from the generated `.vsix`.
1. You can follow [the following instructions](https://github.com/microsoft/CoreTemplateStudio/wiki/Tools:-WTS-Packaging-Tool) to create the package.
2. If you have permissions, you can download the `.vsix` from the *Build Pipeline*.

**Note**: You will also need to update the `Allowed Packages` with the `.mstx` hashes in the file `CoreTemplateStudio.config` within the proper folder depending on the OS you are working (*win32* for instance, when developing on *Windows* for example).

Tests

Client Tests

Currently, we use Jest and React Testing Library for our unit tests which was set up by create-react-app.

To run the client tests, go to src/client and run yarn test to run all the tests. Running this execute tests in files that end with *.{spec,test}.{js,jsx,ts,tsx}.

More info:

• Jest
• React Testing Library

Template Tests

Currently we use scripts to test the generated code. The scripts are located in src/extension/src/scripts. The generate-tests script generates all the different permutations of a Fullstack project (without azure services). Afterwards the run-tests script installs the dependencies for the generated project, runs yarn start, yarn lint and yarn test on all the generated projects.

To run the template tests go to the extension folder and run yarn template-tests to run the tests.

Under the Hood

The Architecture of this app was inspired by the vscode-webview-react

Find some notes about it below if you wish to get started with it: repository by rebornix:

• We inline the initial html <!DOCTYPE html> ... content in src/extension/src/reactPanel.ts when creating the webview
• For all resources going to the webview, their scheme is vscode-resource
• We add a baseUrl <base href="${vscode.Uri.file(path.join(this._extensionPath, 'build')).with({ scheme: 'vscode-resource' })}/"> and then all relative paths work.

Troubleshooting

You may encounter some issues when using or developing in WebTS. It could be due to folder permissions, missing to create the Template packages,... Find below a list of folders that you may be interested in visiting and removing if this happens to you.

• You need permissions to write on the local WebTS folder, where you can find the Logs and Templates folders.

• Web Template Studio may be missing execute permissions on the corets-cli folder, can check full path on the table below, where the Core Template Studio CLI is located.

• The template cache is located in the .templateengine folder. Template caches are isolated by environment.

Note: If you clean or remove the corets-cli folder, you should make sure that you re run the build-all.sh script. Otherwise, if you removed the Templates or the Template Cache, you need to Launch the Web Template Studio wizard again.

Warning: When you are debugging the application, a shortcut to the Templates folder of your code is used. Mind that everything you modified there, will be changed on the local repository.

Useful folders

To make it easier for you to see which folder is used on the different OS, we added a summary table below:

Environment	Description	Folder
Windows	Core Template Studio CLI	%userprofile%\.vscode\extensions\wasteamaccount.webtemplatestudio-[environment]-[version]\src\corets-cli\
	Logs and Templates	%LocalAppData%/WebTS
	Template cache	%userprofile%\.templateengine\[environment].[platform].Any
Mac	Core Template Studio CLI	/Users/[username]/.vscode-server/extensions/wasteamaccount.webtemplatestudio-[environment]-[version]/src/corets-cli/
	Logs and Templates	/Users/[username]/.local/share/WebTS
	Template cache	/Users/[username]/.templateengine/[environment].[platform].Any
Linux	Core Template Studio CLI	//home/[username]/.vscode-server/extensions/wasteamaccount.webtemplatestudio-[environment]-[version]/src/corets-cli/
	Logs and Templates	//home/[username]/.local/share/WebTS
	Template cache	//home/[username]/.templateengine/[environment].[platform].Any

Below you have an overview of the different folder names for the different environments:

Environment name	Description	.vsix folder name	Template Cache Folder Name
WebTSDebug	Debug extension locally	-	WebTSDebug
Local	Local vsix	local	Local.Web.Any
			Local.RN.Any
Nightly	Nightly version	nightly	Nightly.Web.Any
			Nightly.RN.Any
Dev	Marketplace version	dev-nightly	Dev.Web.Any
			Dev.RN.Any

Learn more

• All docs