⏐ 5 min read
If you are more experienced, you may be saying “duh, that’s obvious it’s an electron app”. Not everyone has the experience to make this corollary, and I think it would be a shame if that fact passes people by. Being able to hack your code editor in a language that you know already is a great opportunity. Customizing something you use a lot can be enormously rewarding. 🏆
Here is the repo of examples.
I duplicated the format of Microsoft’s README, but with one big exception. They have a table listing the examples with 3 short fields, I made a short section for each example with a screenshot, a description, and a few other relevant fields.
I found it a slog to understand what example correlated to what part of the UI, you have to click on each folder to find out if you are not sure. There isn’t a good guide to give an overview of the UI. You may not be able to guess where a
progress lives or what a
webview is, without digging deeper. There has been some recent efforts to improve this in the docs, but the info is still spread out and lacks screenshots.
To help with this, I wrote a more complete introductory guide. What I found was really missing in the docs, was a clear overview of the architecture of the API, and tying the API to actual UI. It can be a guessing sometimes to find out what functions you would use to modify some part of the UI. You can find this in the section Architecture overview of the API. The guide also covers getting a project set-up,and how to interpret the API without any TypeScript knowledge.
A word on understanding the API
If you look closer at the TypeScript examples, the first two are :
Webview and a
Webview View. That’s not a mistake. They are 2 different things. They are named that way in
There is a guides section in the docs that has guides that cover different aspects of the API with varying degrees of detail and clarity. The webview API guide is one of the most detailed and probably will clear things up for you, but it’s not the easiest of reads. I found myself sleuthing around quite a bit to figure out how things worked. 🕵️
webview, you can look at the source code of my extension Snippets Ranger.
Often, it is easier to look at a good example than the API reference. You only get the minimum info in an function description.
I had to see an example to understand what the
viewType was exactly. 🤦 Really it is an ID. Just keep this in mind when you are looking through different parts of the API. You may ping pong around a bit to find all the answers you need.
I don’t want to be hard on anyone who builds a big product like this. It is hard to build good APIs, and documentation often is the last thing to do on the back of a lot of other stuff. But I did find it hard to get to grips with the Extension API. It did not feel intuitive.
It could be me, of course, but I don’t think it’s just me! A good API breathes an easy familiarity that gives you the power to guess function names without needing to look them up. I had to look most things up.
I did break through to the other side eventually. Now I can say that I have a good understanding of big portions of the API, but the knowledge was won the hard way. I did have fun making some extensions, but it was peppered with frustration also.
A word on publishing extensions
There is a CLI tool called vsce for packaging and publishing extensions. It’s easy to use. This will create a
vsix package that can be installed as an extension.
# myExtension.vsix generated
The Publishing Extension guide covers the bases for learning how to publish an extension but people do trip up along the way (I did). I contributed to the docs to try to make a couple of steps clearer!
It’s not complicated but you have to follow the steps closely to succeed. You need to have a microsoft account and pick some settings in an azure dashboard. You’ll get a publisher ID and key, and with them you can use
vsce to publish the extension.
The problem is that a couple of the steps seem arbitrary and you may be tempted to leave something out. Just check the boxes like the guide says! If you get stuck, you can always upload your
vsix file to the marketplace dashboard at https://marketplace.visualstudio.com/manage/.
For VS Codium, the marketplace is Open VSX Registy. The process has changed since I did it, but I found the registration a smoother experience than with Microsoft - less steps, less info required. Now, it is part of the Eclipse Foundation, read here for more info on publishing.
I use this github action to automate publishing of an extension to both marketplaces, publication is triggered when the
main branch is updated. There a couple of other github actions if you just want to do publish to visual studio marketplace.
A word on bundling
There is a guide that discusses using webpack and ESBuild. A simple config will is sufficient for most cases, if you make a
webview the config needs to do more to handle images and CSS files. Most of my published extensions use webpack if you want to see a real example.