How to create your own Visual Studio Code extension

In the space of only a couple of years, Visual Studio Code went from a curiosity to a juggernaut in the editor and IDE space. Much of VS Code’s popularity is due to its extensibility: Just about every common programming language, file type, development tool, or cloud service has a VS Code extension available for it.

Sometimes, though, you need to roll your own extension. And while making a Visual Studio Code extension still requires some heavy lifting, the lifting isn’t as heavy as it used to be. In this article we’ll take a quick tour of the tooling now used to help create Visual Studio Code extensions, and show you how to get started with a simple extension that you can then build out on your own.

Install Node.js and Yeoman

Visual Studio Code extensions are written in JavaScript, as is much of Visual Studio Code. If you don’t know about the Node.js JavaScript runtime, or JavaScript itself, read up on them first. You can optionally use TypeScript to develop Visual Studio Code extensions, but we’ll use JavaScript here since it’s more widely known.

First, install the following if you haven’t already:

• Visual Studio Code
• Node.js

After Node.js is installed, you’ll use the Node package manager to install Yeoman, which is a system for bootstrapping new projects in Node.js, and generator-code, which is a package that uses Yeoman to generate a new Visual Studio Code extension project from a template.

To install Yeoman and generator-code, run the commands below from the command line. Note that the Yeoman install process may take a couple of minutes.

npm install yo
npm install generator-code

Run the Visual Studio Code Extension generator

The next step is to run generator-code to create the scaffolding for your extension. First, create a new directory to hold your Visual Studio Code extension project. Then switch to your new directory, launch the shell, and run this command:

yo code

You should be presented with a text menu of choices for what kind of extension to create; choose “New Extension (JavaScript).” You will then be prompted to supply some information about the extension you’re creating:

• Name: The public name of your extension; it can be anything you want.
• Identifier: The internal name for your extension; it should be an identifier that you would use in code (e.g., a single word, or multiple words separated by underscores).
• Description: Any text to describe the extension; keep it brief for now, as you can always alter this later.
• Enable JavaScript type checking: Set this to No for now; you can always alter this later if you need it.
• Initialize a Git repository: Select Yes, except in the unlikely event you’re not using Git to manage your projects.
• Which package manager to use: Choose Yarn or NPM; we’ll continue using NPM here.

Once the script finishes running, you’ll see a subdirectory named according to your Identifier above. That directory should contain your newly created extension.

Finally, test the newly created extension to make sure it’s working. Open the directory with Visual Studio Code, and press F5 to launch the Extension Development Host. This will kick off another instance of Visual Studio Code, this one running your prototype extension.

In that new VS Code window, press Ctrl-Shift-P to bring up the command palette, and type “hello.” You should see a command named Hello World come up. Click on it, and a notification box with the text “Hello World!” should pop up. You can go back to the original VS Code window and press Shift-F5 or click the Stop button at the top to close out the Extension Development Host.

One very handy feature of the Extension Development Host is that it’s just another instance of VS Code. If you open a project directory in the Extension Development Host, you can use that project in conjunction with the extension you’re developing, and thus test it live. 

IDG

Build out your new Visual Studio Code extension

The generator-code project creates the most basic wiring and plumbing needed for a functioning extension. If you look in the extension directory, you’ll see several files:

• vsc-extension-quickstart.md provides some instructions for creating and using the extension.
• extension.js is the actual code for the extension. The entire extension doesn’t need to fit into this one file, but this is the default entry point for the extension.
• jsconfig.json controls how the project’s JavaScript code is handled by the Node.js runtime. You generally don’t need to change anything here.
• package.json contains the packaging information for your extension. Some of the fields, like name or description, should be familiar and can be edited as needed. The main field describes the entry point for the extension; by default it’s extension.js, but it can be changed if needed. However, the devDependencies fields should be left as-is.
• README.md is a boilerplate README file for your extension that you can customize to suit.
• CHANGELOG.md is a blank change log for documenting what you fix or add as you go.

Open extension.js and you’ll find two functions: activate and deactivate. The first registers all of the actions taken by the extension through VS Code’s APIs; the second performs any unregistering actions. In the example, deactivate will remain empty, since we won’t make any changes to our extension that will require undoing.

The activate example uses a few VS Code API functions, which you will likely find helpful to play with on your own:

• vscode.commands.registerCommand adds a command to the command palette under the extension’s name.
• vscode.commands.showInformationMessage pops up the information box at bottom right, with a supplied text.

Here is a simple way you can modify the extension to do something a little more interesting. Replace the showInformationMessage command with the following:

vscode.window.showInputBox({ prompt: "Say something" }).then(msg => vscode.window.showInformationMessage(msg));

Now, when you run the extension, you will be prompted with “Say something” in the command palette. Whatever text you enter will be echoed back in the pop-up message box.

Test your new Visual Studio Code extension

The scaffolded project also includes a skeleton for tests to run against your extension. Test-driven development makes developing in dynamic languages like JavaScript less fraught with unpleasant surprises, so it’s a good idea to fill out a test suite for your extension as you add features to it.

Tests are written using the Mocha framework for JavaScript. To get them to work, you’ll need to install them from the console within Visual Studio Code:

npm install mocha
npm install glob

To get an idea of how the tests are constructed, look in the /test/suite directory of your project. There, you should see a file named extension.test.js that contains a few sample tests. These tests don’t actually test anything in your extension; they’re there only to show what the format for a test looks like.

To run your tests on the project, go to the Debug and Run view, select Extension Tests from the drop-down menu next to the green arrow at top left, and click the green arrow or press F5 to start debugging. This will launch the Extension Development Host and execute the tests. Once the tests run, you should see the results in the Debug Console for the instance of Visual Studio Code where you’re developing the extension.

IDG

Where from here?

Once you’re comfortable with the VS Code extension development and test tools, the next step is to crack open the documentation for the VS Code JavaScript API and start experimenting. You might find APIs in there that give you ideas for extensions you never previously considered.

If you could use some guidelines for writing better tests, dig into the Mocha documentation to see how to write tests that cover various conditions and use cases.

And be sure to install other extensions that help you develop with JavaScript in VS Code. ESLint is one of the most common and useful.

Finally, one of the most effective ways to learn how to write software is by example. Browse the VS Code Extensions Marketplace for extensions that hew closely to the one you’re aiming to develop. Studying its source should give you ideas about how to go about writing your own extension.