Salesforce Development Tools for Visual Studio Code

Introduction

This repository contains the source code for our Visual Studio Code (VS Code) extensions for Salesforce DX.

We will be publishing these extensions to the VS Code Marketplace shortly and will make an announcement when they are available.

Pre-requisites

1. This repository uses Lerna to manage it as a monorepo. Please install Lerna globally using npm install --global lerna.
2. We use tslint so please install it using npm install --global tslint.
3. It is preferred, though not required, that you use the Insiders version of VS Code from here.
4. There is a list of recommended extensions for this workspace in .vscode/extensions.json. The first time you open VS Code on this workspace, it will ask you to install them. Please do so since this includes the linters and formatters.

Pre-requisites for Windows Development

These are instructions for developing the extensions on Windows since there are some quirkiness with the way Windows behaves. This does not affect the actual extensions that we distribute.

1. Same as above.
2. You should use Bash Shell instead of Powershell or the Command Prompt.
3. If you want to use the integrated terminal in VS Code, you can see that following the instructions here;
4. You should install VS Code Insiders from here. Without this, you won't be able to run the end-to-end tests while VS Code is open. You will see an error of the form "Running extension tests from the command line is currently only supported if no other instance of Code is running." To circumvent that you could close VS Code each time you run the tests. Or, you can install the Insiders version so that it can run the tests in Code while you work in the Insiders version.

Structure

Packages

The packages directory contains the different npm packages. The naming convention is that anything with 'salesforcedx-vscode' is a VS Code extension.

Typical workflow

You would only do this once after you cloned the repository.

1. Clone this repository from git.
2. cd into salesforcedx-vscode.
3. We develop on the develop branch and release from the master branch. At this point, you should do initiate a git checkout -t origin/develop unless you are working on releasing.
4. npm install to bring in all the top-level dependencies
5. Open the project in VS Code.

You would usually do the following each time you close/reopen VS Code:

1. [Optional] Open the Command Palette > Tasks: Run Task > Bootstrap (this essentially runs npm run bootstrap). This is required if you change the dependencies in any of the package.json.
2. If you wish to build, you can invoke Command Palette > Build Task (Ctrl+Shift+B or Cmd+Shift+B on Mac). The errors will show in the Problems panel. There is a known issue with the mapping so clicking on the error won't open the file.
3. In VS Code, open the debug view (Ctrl+Shift+D or Cmd+Shift+D on Mac) and from the launch configuration dropdown, pick "Launch Extensions".
4. In VS Code, open the debug view (Ctrl+Shift+D or Cmd+Shift+D on Mac) and from the launch configuration dropdown, pick "Launch * Tests".

For more information, consult the VS Code doc on how to run and debug extensions.

When you are ready to commit

1. Run npm run lint to run tslint in more thorough mode to identify any errors.
2. Some of the items can be fixed using tslint --project . fix. Some you might need to fix them manually.

This linting steps should be done later as part of the continuous integration runs but that is how you would check locally first.

List of Useful commands

These commands assume that they are executed from the top-level directory. Internally, they delegate to lerna to call them on each npm module in the packages directory.

npm run bootstrap

This bootstraps the packages by issuing an npm install on each package and also symlinking any package that are part of the packages folder.

You would want do this as the first step after you have made changes in the modules.

If you change the dependencies in your package.json, you will also need to run this command.

npm run compile

This runs npm run compile on each of the package in packages.

npm run clean

This run npm run clean on each of the package in packages.

npm run watch

This runs npm run watch on each of the package in packages. The --parallel flag tell it to run each in a separate process so that it won't block the main thread.

npm run test

This runs npm test on each of the packages. The --concurrency 1 is essential for VS Code extension tests since they require an instance of Code to run in. And, only one instance of that can be running at a single time.

npm run lint

This runs npm lint on each of the packages. If there are no errors/warnings from tslint, then you get a clean output. But, if they are errors from tslint, you will see a long error that can be confusing – just focus on the tslint errors. The results of this is deeper than what the tslint extension in VS Code does because of semantic lint rules which requires a tsconfig.json to be passed to tslint.