My team is officially launching an extension for VS Code today. And wow, you can learn a lot by shipping a product.
The process of building an extension for VS Code and launching it in their marketplace was surprisingly enjoyable and more importantly an invaluable learning experience. So I wanted to share a way for anyone of any skill level to build and launch their own extension—a mini “product” that can be immediately available for millions of VS Code users.
If you’ve never built an extension before, designing your own theme is a great to way to familiarize yourself with the tools and processes required to build VS Code extensions.
This quick tutorial is going to take you all the way from opening VS Code to publishing your first theme in the marketplace. Jump ahead if you’re already familiar with certain steps.
Getting started with color themes
VS Code has tons of out-of-the-box themes that you can access using the command Preferences: Color Theme which opens a menu of available themes, like Light+, Dark+, Monokai, Red, and others. If you’re looking for even more customizations, the VS Code marketplace has thousands of themes available to download.
I recommend trying a few different themes. Themes are the setting for all of your development—the backdrop for the magic of software development. Themes can inspire you (or conversely depress or bore you). So while subtle, themes really matter.
The basic workflow that we’ll follow to build a VS Code theme can be summarized with three key steps:
- Create the framework for your extension using an extension generator
- Design your extension by adding color customizations
- Publish your extension to the marketplace by creating a Microsoft account and publisher profile
The timer starts now!
Setting up your environment
To make an extension for VS Code, you will need to install the following tools:
Node.js is a popular open source JavaScript runtime that executes JavaScript outside of the browser. VS Code has support for JavaScript and TypeScript out-of-the-box as well as Node.js debugging. You'll need to have Node.js installed to be able to run your application in debug mode in VS Code. Check out the different installers if you don't already have Node. There are many different ways to install Node across different platforms, but the most straightforward way to install Node is to use the official installers from the Node website.
You can check that you have Node installed by opening up the terminal and entering node -v. Also make sure that npm, the Node Package Manager that handles package installation for Node tools, is installed with npm -v.
Once you have installed Node, you can install Yeoman and the Visual Studio Code Extension Generator. Together these tools will automatically build the basic framework of your extension with the necessary files.
Yeoman is known as the “web’s scaffolding tool.” It provides easy access to a large ecosystem of generators to quickly jumpstart projects. The Visual Studio Code extension generator will guide you through the process of laying out your extension’s file structure.
To install both Yeoman and the VS Code extension generator, you can use npm, the package manager for Node. Open the terminal and enter:
npm install -g yo generator-code
Once the extension generator is installed, you’re ready to start building your color theme extension.
Building the scaffolding for your extension
In your terminal, navigate to a directory in which you would like to create your extension. The extension generator will create a new folder in this directory with all of the files needed to build a working extension. To run Yeoman and the VS Code extension generator, enter:
yo code
The extension generator now asks you a series of questions needed to create a new extension.
There are a few types of extensions that the generator can help create. We’re going to be building a color theme, so choose that option.
What type of extension do you want to create? New Color Theme
The next question asks about TextMate themes. TextMate rules change syntax colorization. Configuring TextMate rules is a more advanced skill that requires knowledge of TextMate grammar. Until you’re familiar with TextMate, start fresh.
Do you want to import or convert an existing TextMate color theme? No, start fresh.
Now it’s time to name your extension. Naming is going to be key to getting user interest and adoption. My color theme uses a shade of blue from our Code Time extension and is named after our mascot, Cody.
What’s the name of your extension? Cody Blue
The identifier for your extension defaults to the name of your extension, but all lowercase and with hyphens swapped in for spaces.
What’s the identifier of your extension? cody-blue
Next, you can write a short description of your theme and pick a name that is shown to users.
What’s the description of your extension? A dark blue theme
What’s the name of your theme shown to the user? Cody Blue
Lastly, select a base theme. You will build your theme on top of the defaults for the base theme.
Select a base theme: Dark
After you answer the last question, the generator will create the following files in a folder named using your extension’s identifier:
├── .vscode
│ └── launch.json
├── themes
│ └── Cody Blue-color-theme.json
├── .vscodeignore
├── CHANGELOG.md
├── package.json
├── README.md
└── vsc-extension-quickstart.md
What do each of these files do?
The .vscode folder contains launch.json, a file that configures how the debugger is launched for your project. The .vscodeignore file determines which files are ignored when an extension is installed. We can ignore these files and folders for now, as their default settings are fine.
The file vsc-extension-quickstart.md has some instructions on how to get started designing and building your theme extension. It’s worth giving it a quick read.
README.md is a place for you to add any descriptions or text you’d like users to read in the marketplace or on your GitHub repo. Similarly, CHANGELOG.md is where you will be able to manually make note of feature changes as you update your extension.
The most important files, however, are package.json and color-theme.json. package.json contains all of your extension’s settings. color-theme.json contains all of your color customizations and is where you will design your theme.
Choosing your theme’s color customizations
To get started editing your extension, open your extension project in VS Code.
To preview and debug your extension, hit Function + F5 to run the extension in an Extension Development Host window. The Extension Development Host allows you to run your extension in a separate window, making it easy to debug and see your extension in action. To exit debugging mode, simply close the new window.
Try running your unedited extension in an Extension Development Host window.
With the extension generator, I selected the base theme as “Dark” which looks like this:
To make color tweaks, go to the theme file located in the themes folder in your extension. The theme file is a JSON file that has the structure: your-extension-name-color-theme.json.
At the top of the JSON file, you’ll see a section called colors. This is where you will make most of your edits. The colors section comes with a few default colors.
Let’s delete them for now, so you can use your own colors.
There are two types of customizations that can be made: workbench and syntax. Workbench customizations change the color of the editor and its views, while syntax customizations affect the look of the source code in the editor.
For now, let’s focus on making workbench customizations, which cover the most prominent features of VS Code.
Add the following lines to your theme file in the colors section. These settings change the main parts of the editor, like the title bar, menu bar, activity bar, sidebar, and status bar.
// title bar (macOS)
"titleBar.activeBackground": "#384357",
"titleBar.activeForeground": "#afafaf",
"titleBar.inactiveBackground": "#29303f",
"titleBar.inactiveForeground": "#afafaf",
// menu bar (PC/Linux users)
"menu.background": "#384357",
"menu.foreground": "#afafaf",
// activity bar
"activityBar.background": "#384357",
"activityBar.foreground": "#00B4EE",
"activityBar.inactiveForeground": "#afafaf",
// side bar
"sideBar.background": "#384357",
"sideBar.foreground": "#afafaf",
"sideBarTitle.foreground": "#00B4EE",
"sideBarSectionHeader.background": "#384357",
"sideBarSectionHeader.foreground": "#afafaf",
// status bar
"statusBar.background": "#384357",
"statusBar.foreground": "#afafaf",
"statusBar.noFolderBackground": "#384357",
"statusBar.noFolderForeground": "#afafaf",
"statusBar.debuggingBackground": "#384357",
"statusBar.debuggingForeground": "#afafaf",
"statusBarItem.hoverBackground": "#29303f",
// editor
"editor.background": "#191e27",
"editorLineNumber.foreground": "#afafaf",
"editorLineNumber.activeForeground": "#00B4EE",
// editor groups and tabs
"editorGroupHeader.tabsBackground": "#14181f"
The color theme JSON file is simply a list of key/value pairs. The key is the feature you are customizing and the value is the hex color code you would like to assign to that feature. The resulting theme file should look like this:
You’ll notice that after you enter the hex code for a color, VS Code shows a color picker if you hover over the hex code again. The pop up will also tell you what the feature you are changing will do to your editor’s appearance.
Try picking your own values to update your color scheme.
To see the new colors in action, again hit Function + F5 to run the extension in an Extension Development Host window.
The changes above should look like this:
Want to see what other themes have customized? Check out Shades of Purple and poke through its GitHub repo for even more inspiration.
Want to change even more? The VS Code documentation lists every feature that you can customize. You can edit everything from the integrated terminal to notification toasts to dropdown menus. Feel free to add any other changes you’d like.
Publishing your theme extension to the VS Code marketplace
Once you are satisfied with your theme’s customizations, you can publish your extension to the VS Code marketplace. The marketplace is a great way to showcase your theme so other VS Code users can find and install your theme.
First, update your README to tell users about your theme. Your README will be visible in the VS Code extension marketplace.
To publish your extension, you’ll need to install Visual Studio Code Extensions, a command line tool for packaging, publishing, and managing extensions. Open up your terminal again and run:
npm install -g vsce
The fastest way to gain access to the VS Code marketplace is to create both a Microsoft account and a publisher profile on the management page for the VS Code marketplace. Here you can create a publisher profile to add your extensions to the marketplace.
Once you've created a publisher, be sure to go back to your extension and edit the package.json file by adding "publisher”: “publisher-name” as a new key/value pair using your newly created publisher name.
Once you create your accounts, you will automatically be redirected to a page called Manage Publishers & Extensions.
You have the option to upload your extension, which will then be available in the VS Code marketplace. Simply run vsce package and upload the resulting VSIX file. The VSIX file contains all of the information needed to install and run your extension.
However, if you want to publish from the command line (which I’d recommend because it’s easier to push updates to your extension), you will need to create an Azure DevOps Organization.
To do so, click on your name or email in the top right of the navigation bar. This will take you to a page to create a new organization. Click ‘Create new organization’.
The next window will let you create a name for your Azure DevOps organization.
Once you’ve created your organization, click on your avatar in the top right of the navigation bar. Scroll down and click on Security.
Click ‘Personal access tokens’ and create a new token. Select the following settings:
You’ll now see an access token. Copy it, as you will not be able to see it again.
You can now associate your publisher name, which you created earlier, with vsce. In your terminal, enter:
vsce login (publisher name)
Next, vsce will ask you for your Personal Access Token, which you created through your Azure DevOps organization. Enter the token when prompted.
Again in the terminal, navigate to the folder containing your extension files. To finally publish your extension, enter:
vsce publish
You will receive a warning that you don’t have a repository. Follow the prompts to ignore this for now.
You’re done! Shortly after publishing, vsce will give you a link to see your extension in the extension marketplace.
You can also go back to the publisher manager page to see the status of your extension.
Making a few final touches
It’s good practice to add an icon to your extension and a GitHub repo where others can see the source code. You will need a GitHub repo to add an icon.
First, create a repository from your extension folder and push it to GitHub (or another repository hosting service).
Find the URL of your repository and add the following snippet to package.json:
"repository": {
"type": "git",
"url": "https://github.com/geoffstevens8/cody-blue"
To add an icon, create a folder called images in your extension folder. Add an image to this folder you would like to use as your icon. The icon should be a PNG and at least 128x128. I chose a solid color from my theme.
Next, add the following key/value pair to package.json:
"icon": "images/icon.png"
Before you publish again, be sure to increment the version number in package.json. Once you’ve done that, you can publish again by simply running vsce publish.
Want to see my theme? Find my theme in the marketplace and the source code on GitHub.
Let the world know
Finally, if you want the world to know about your first mini “product” or them extension launch, you can get help tweeting it out or launch on Product Hunt.
Here’s how you build a simple link with a message your friends and network can easily share.
Start with: https://twitter.com/intent/tweet?text=
After = add your text, but make sure to replace all spaces with %20—as you can see in the example below.
Now the fun begins—keep checking back on your extension web page to see how many downloads you get!
If you enjoyed this tutorial, check out the extension my team just launched: Code Time.
Top comments (2)
Wow. That's a lot easier than I expected. Definitely going to dive into this soon!
Do you have a sponsored post about it on Facebook? I think I got targeted there but I missed it.