loading...
ITNEXT

How YOU can build and publish your own extension to VS Code Marketplace

softchris profile image Chris Noring Updated on ・10 min read

Follow me on Twitter, happy to take your suggestions on topics or improvements /Chris

This article is part of a series, this is part I.

Creating a snippet or a color theme in VS Code is all well and good, but what if you created something really great that you want to show a friend or better yet give to the community. For that, we have Visual Studio Marketplace. In this article we will build an extension and bring it all the way to the Marketplace for people to download inside of their VS Code - you can soon call yourself an extension creator

This article will cover the following:

  • scaffold an extension project
  • write extension, in this case, it's about writing snippets
  • publish extension to Visual Studio Marketplace

Ok, we created a snippet in the first article of our series Snippet creation.

It's time to take the next step, let's share our creation with the world. So how do we go about doing that? Well, it's actually just three major steps:

Of course, each of these steps has a lot of substeps to them, but don't worry I will explain them all in detail so you at the end of this article get off your chair and celebrate just like this:

Resources

What we are about to show, is how to create an extension given a Snippets template but there are so many more extensions you could be creating so here are some links to know more once you get through this article:

Scaffold an extension project

There is a scaffolder for this that lets you create a project in like a second. To install the scaffolder simply type:

npm install -g yo generator-code

To scaffold an extension project we just need to type:

yo code

The above will trigger a dialogue in which you need to make some choices. Let's show each screen and see what we need to select:

We got plenty of choices above but let's select New Code Snippets

Next up we get a dialogue asking us to select between importing existing snippets from a folder or create new:

We opt for creating new and therefore we just hit the return key. The step after this is to give our extension a name. This is how it will appear in the Visual Studio marketplace so let's give it a good name, for example like this:

Question after that is identifier. We just hit the return key. This means name and identifier will be the same thing:

There are more questions, you thought you were done;)? Next question is asking you for a description of your extension. This will appear to a user, so make sure it's compelling so they want to install it. You can change it afterward though:

Next step is typing the publisher. Now you are probably thinking. I don't know anything about a publisher, what does it want from me? Well for now come up with a clever name for a publisher, we will create a publisher later that we will register with Visual Studio marketplace, all in good time :)

Above you can see that it's already entered the value chris noring as publisher and that's because I already created a publisher since before, as you haven't, just enter something here for now.

Next step in your dialogue flow is to enter the language id, this means what language this snippet is for. Let's enter javascript or typescript, remember to enter it in small caps like the instruction says:

After this you are actually done. It should list all the files that it needed to scaffold for your extension, like this:

Extension project anatomy

Ok, so now we have our project, let's have a look at what we actually got:

Our project consists of the following, from the top:

  • /snippets/snippets.json, this is where our snippets are created and where we will spend most of our time
  • README.md, this contains information about your project. You need to change the information in here to be able to publish the extension to Visual Studio marketplace. So what info do I put in here? Well, you should tell the user what commands the user will have at their disposal after installing this extension. It's also nice if you provide the user with a history of all the different versions and what they contain. This will show to the user that you are very committed to improving the extension over time
  • ../.yo-rc.json, now this file is outside the project, it contains the publisher name pretty much, no need to change it
  • package.json, this contains some meta-information about the project. Important here is to change version property and increment it as you update and republish your project as you improve it over time.

Ok, so now we understand a bit more about what files are important and where we should go in and change things if we need to.

Create our snippets

Believe it or not but this is the easy part. We have already explained how to create snippets in the first article of this series, here is the link again as a reminder TODO link. We will settle for just showing a screen dump of some snippets, like so:

Ok, so now we have a snippet. Let's try it out next.

Test out our snippets

To try out a snippet we need to install it. To install it we need to do the following:

  • run package command
  • install it from a command window
  • try it out in a suitable file

Ok, so let's start by running the package command in the terminal. Wait, we need a dependency first to do this:

npm install -g vsce

By running the above command we install vsce that installs an executable that we need. We need the executable to run commands like package and publish.

Package and install

Ok then, we have run the above command and we are ready to package, i.e create an installation file:

Ah, error straight away, it doesn't start good or? Well, this is actually quite helpful, it tells us that the user of this extension deserves better, they deserve a well formulated and thought out README me file that will tell me all about this extension. So let's head over to README.md and give it some love.

There are a lot of things written in here but what you actually need to change is the text that goes like This is the README, just at the top. Once that is gone we can try running our package command anew. Just a quick word when editing the README file. My take on it is that it makes sense to give it an initial description and keep a headline like Features and Release Notes. Features in my mind should describe all the available commands and what they do. Release Notes should contain a history log of each version release and what the impact was, like correcting a mistake or adding a snippet.

Once we are happy with the README let's try to run the package command again:

vsce package

This will complain that we are missing the repository property in our package.json. We don't actually need a repository for this to work, it is a nice to have though. We can continue by hitting y. Now it should say that it has created an installation file, like so:

Once we have such a file we are ready to install our extension locally in our environment. This will let us try out our extension to ensure everything works as intended. To install it we have to open a command window. To do that go to View => Command Palette. Then start typing "VSIX". It should show you the following:

Let's select that command. You should be prompted with a file selection dialogue in which you need to select the recently created vsix file. After that VS Code should present an information message at the bottom of your window asking if you want to reload VS Code. After hitting yes your IDE is now ready to be tested out.

Try it out

We have just installed our snippet into VS Code. Because this snippet is meant for TypeScript we need to create a .ts file to see it. so let's create for example app.ts and it should result in this:

If you see the above, it means your snippet works as intended at it's time to give yourself a high five. We are getting closer to Visual Studio Marketplace and developer fame ;)

Publish our snippets

Ok, so we are now at the moment we've all been waiting for. It's time to publish this extension and start seeing your name in neon lights at the Visual Studio marketplace :)

Registering a publisher

Remember how we at the beginning of scaffolding our extension project we were prompted for a publisher name? Well, now it's time to actually create that publisher. So how do we do that?

We need to create an account with Visual Studio Team Service link to VSTS. Once we have created an account here we need to get an Access Token

Access token creation

An Access Token is needed when we publish our extension using vsce in the terminal. We can create an access token by going to our VSTS page and click on the profile in the top right corner and select the menu option "Security". Once there we need to:

  • choose "Personal Access Tokens".

  • Next step is to choose to create a new such token.

  • Give it a suitable name and expiration date and, this bit is important, in the organization dropdown you need to select All accessible organizations or it won't work. The next important field is Scopes. Here you can go with either custom defined or full access. If you are only trying it out try going with full access for now but make sure to revoke that token later and opt for custom defined and set it to the least amount of privileges you can get away with. Usually, you just want it to be able to have Extensions and Marketplace access.

So having gone through the whole access token creation bit we should have an access token staring at us that we can copy to the clipboard.

Make sure to copy it to a suitable place for later retrieval, it won't show again after closing the dialog.

Update token

Sooner or later your token will be out of data. When that happens, regenerate your token and run this in the terminal:

vsce publish -p <token>

This will now use your new token so that next time you publish you only enter:

vsce publish

Publish

Ok, finally we are ready to run the publish command. It's time to run:

vsce publish

This should send our extension to Visual Studio Marketplace. Running the command in the terminal it should show something like this:

Enjoy the fruits of your labor

It will take a few minutes for Visual Studio Marketplace to update. Let's pretend a few minutes have passed and let's go to the URL for Visual Studio Marketplace. If you can't wait, go to https://marketplace.visualstudio.com/manage/publishers/<publisher name> it should have an entry with your extension name and say that it is verifying your extension. Ok let's have a look at our creation:

You should be so proud right now. There it is, your extension, in all its glory, made available for the entire world. Let's show that is the case by searching for it under the extensions tab in Visual Studio Code:

There it is, you typed your extensions name, Visual Studio code showed it to you. You are a proud parent to your extension. Let's also have a look at the detail page, i.e what we wrote in our README:

There it is. This is just the beginning. Now go out, create extensions, I know you can do it !!!

Improve the extension

There are two major things you want to do to improve how people perceive your extension, those are:

  • add a repository
  • add a preview gif

Adding a repository

To add a repository create one on GitHub. Once that is done let's add to our package.json file like so:

"repository": {
"type": "git",
"url": "https://github.com/softchris/node-snippets.git"
}

That's it, it will now show up on the extension page and people will be able to click into your repo and see how you built things and if you want help you with it by submitting PRs

Adding a preview GIF

If you've downloaded extensions before you might have noticed how some of them comes off really professional with an intro video showcasing the snippets. This video is really a GIF and adding a GIF to a markdown is pretty easy:

![alt text](images/node-snippets.gif "Using the snippet")

Note above how we refer to the directory image. It will be able to resolve this by looking inside your repository and expect to find that image directory. So that's why you need the repository set for this to work. No repository, no preview image.

Your marketplace will now look something like this:

Above is a still image so it won't showcase this as an animation in this blog post but it will work for real.

I recommend producing the needed video with Camtasia or some free option and then convert it to gif once you are done with the recording.

Summary

in summary, we learned the following:

  • Create an extension project, by using a scaffolder
  • Add some snippets to our project
  • Testing out our snippet locally, as a way to ensure if worked before we publish
  • Set up for publishing, by installing vsce and generating an access token
  • Gazed upon our beautiful creation in Visual Studio Marketplace
  • Micdropped, by searching for and finding our extension through VS Code

Go out, show the community what you got. Want to tell me about it? Just tweet to @chris_noring

Snippets by me

I'm maintaining a couple of snippet extensions currently. All feedback welcome:
My extensions

Discussion

pic
Editor guide
Collapse
dzhavat profile image
Dzhavat Ushev

Great post. I had troubles with some of the steps because I felt that some information was missing and took me a bit more time to figure things out.

One thing in particular was that I was asked for Personal token already when running vsce package and you have that section after.

Anyway, I just published my first extension and I’m quite happy :)

Collapse
softchris profile image
Chris Noring Author

Appreciate your feedback Dzhavat, I'll make sure to change the order and congrats on your first extension :) Let's hope for many more, it's a great feeling right?

Collapse
dzhavat profile image
Dzhavat Ushev

Yes, it is! :)

Collapse
th3n00bc0d3r profile image
Muhammad

Great Post man... Gonna try it out for sure.

Collapse
softchris profile image
Chris Noring Author

Thank you.. :)

Collapse
ibra4 profile image
ibrahim ahmad

Great ✌️