Azure DevOps Extension Hot Reload and Debug

This repository demonstrates how to load an Azure DevOps extension's code directly from the dev machine rather than bundle all the code and deploy it through the marketplace. We will leverage the (somewhat hidden) capability in Azure DevOps to load content from localhost, which will enable us to use hot reload and debug in VS Code.

For more information about our motivation in developing this project, see our blog post.

Prerequisites

Download and install the following tools

1. Visual Studio Code
2. Firefox (because the VS Code Debugger for Chrome extension doesn't support iframes yet)
3. The Debugger for Firefox VS Code extension
4. The tfx-cli npm package
5. The webpack npm package
6. The webpack-dev-server npm package

If you would prefer not to install the npm packages globally, you can add them to devDependencies in your package.json file and invoke them with scripts. You can use the package.json in this repo as a template for scripts and to ensure you have the correct versions of packages in your extension.

Starting a new extension

If you're starting a new extension, you can either clone this repo or use our Yeoman generator to scaffold a new extension with support for hot reload and debugging. (The following sections provide information about how we configured the template.)

Clone

git clone https://github.com/microsoft/azure-devops-extension-hot-reload-and-debug.git

Yeoman

npm install -g yo
npm install -g @microsoft/generator-azure-devops-extension
yo @microsoft/azure-devops-extension

Enabling an existing extension

To reconfigure your existing extension, follow these steps to get everything working. This configuration assumes you know the basics of how to set up an Azure DevOps extension using Typescript and webpack. For more information, see the Azure DevOps extension docs or the azure-devops-extension-sample repo.

Extension manifest

The "trick" to get everything working is to set baseUri in the extension manifest file to https://localhost:3000. This setting tells the extension to load resources from your local dev server rather than the packaged extension.

Your port can be different than 3000. For the purposes of this document we will use 3000 consistently, but if you have a port conflict, you can change this to any port that works for your environment.

We recommend using an overrides JSON file to set this value only for your dev builds. The tfx command line utility supports overriding any values in your extension manifest with the values in this file while packaging by passing the --overrides-file parameter. We will use this feature to set the value of baseUri differently for dev vs. release builds.

Create an overrides JSON file with the following content for your dev build called dev.json:

{
  "id": "[extension-id]-dev",
  "public": false,
  "baseUri": "https://localhost:3000"
}

You can leave default values for these properties in your extension manifest or, for consistency, you can delete them from your manifest and create a release.json overrides file for release builds as well (in which case we suggest you create a configs folder to keep things organized):

{
  "id": "[extension-id]",
  "public": true
}

You can move additional settings you would like to override for specific build configurations from the extension manifest to the dev.json or release.json files if you choose. These values are just the recommended minimum settings.

Webpack config

You will need to enable source maps in webpack.config.js. Set the devtool property to inline-source-map. You will also want to set devServer.https to true and devServer.port to 3000.

module.exports = {
  devtool: "inline-source-map",
  devServer: {
    https: true,
    port: 3000,
  },
  // ...
};

For this example, we've validated that inline-source-map works well. However, you may find that another source map option works better for your project.

By default, webpack serves its compiled, in-memory files directly under localhost:3000 but the extension is looking for files in the dist path. To fix this discrepancy, set output.publicPath to /dist/ in the webpack config. Now webpack will serve files from localhost:3000/dist and your extension should load correctly.

module.exports = {
  output: {
    publicPath: "/dist/",
    // ...
  },
  // ...
};

Your extension may load fine without this change because webpack will serve files from the filesystem if it does not have an in-memory version to serve instead. Therefore, webpack may serve files from the dist folder if it exists, but hot reload will not work.

In order to make webpack copy HTML files from the src folder to the dist folder, you need to add the copy-webpack-plugin npm package to your project, and then add the following lines to your webpack.config.json file. These changes will configure webpack to copy all HTML files from src:

const CopyWebpackPlugin = require("copy-webpack-plugin");
// ...

module.exports = {
  plugins: [new CopyWebpackPlugin({ patterns: [{ from: "**/*.html", context: "src"}] })],
  // ...
};

VS Code's launch.json

The last configuration change we need to make is to set up a debug configuration for VS Code that launches Firefox with the correct path mappings. Add a path mapping with url set to webpack:/// and path set to ${workspaceFolder}/. To avoid restarting Firefox every time you debug, you can also set the reAttach property on the configuration to true.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Firefox",
      "type": "firefox",
      "request": "launch",
      "url": "https://localhost:3000/dist/hub/hub.html",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack:///",
          "path": "${workspaceFolder}/"
        }
      ]
    }
  ]
}

Using hot reload and debugging

Now that you have configured the extension, follow these steps to use hot reload and start debugging your code.

Install dependencies and build the extension

Before we deploy the extension, we need to install its dependencies and compile the code using the following commands:

npm install
webpack --mode development

Deploy your dev extension to Azure DevOps

You will need to deploy your extension to the marketplace at least once using the following command:

tfx extension publish --manifest-globs vss-extension.json --overrides-file configs/dev.json --token [token]

The [token] here is an Azure DevOps PAT (personal access token) with the Marketplace (Publish) scope and access set to All accessible organizations. For more information, see Authenticate access with personal access tokens.

After the extension is published, share it with your Azure DevOps organization and install it. Navigate to a project and you will find a new hub called "Hello World!" When you click it, you will notice that the hub won't load correctly. It isn't loading because the extension is configured to load all its resources (html, images, etc.) from localhost:3000, but the dev server isn't running yet.

Launch your dev server

Start the webpack-dev-server with:

webpack-dev-server --mode development

Now if you go to https://localhost:3000/dist/hub/hub.html in your browser, you should get an untrusted certificate error page. Select Advanced and then select Accept the Risk and Continue.

Go back to Azure DevOps and reload. Your extension should now load correctly and any changes to the source code will cause webpack to recompile and reload the extension automatically.

Although most code changes will be reflected immediately, you may still need to occasionally update your extension in the marketplace. The dev extension loads all its resources from the webpack-dev-server, but the manifest itself is being loaded from the published code. Therefore, any changes to the manifest file will not be properly reflected in Azure DevOps until the extension has been republished.

Launch your VS Code project to debug against Azure DevOps

In VS Code, press F5 to start debugging (making sure the webpack-dev-server is still running). The default launch configuration should be set to Launch Firefox.

Once Firefox starts up, you will have to go through the steps of allowing the localhost:3000 certificate again and log into your Azure DevOps account. From now on, if you leave this Firefox window open, the debugger will reattach instead of starting a clean Firefox instance each time.

Once you are logged in to Azure DevOps, your extension should be running. Set a breakpoint in a method in VS Code and you should see that breakpoint hit when that method executes.

Chrome configurations are included in the sample as well in case the Debugger for Chrome extension eventually supports iframes. However, debugging iframes is only supported in the Debugger for Firefox extension at this time.

Conclusion

We hope you enjoy the ability to iterate faster and debug right in VS Code!

If you want to start a new extension project, check out the Yeoman generator our team has built to get everything set up faster. Also, if you would prefer to debug your extension in Chrome, please upvote this GitHub issue and add in any relevant comments.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.