Create VSCode extension from scratch to testing, documentation, and publishing
By Amirmasoud
Introduction
In this post, We would try to develop and publish a visual studio code extension using VSCode samples, APIs, and TypeScript. The extension we will make is called Oops and is currently available at the VSCode Marketplace and GitHub if you want to check it out for yourself.
This extension will be a simple and straightforward one as the functionalities are limited to these four items:
<li>
Can convert a directory to a file<ul>
<li>
Check if the directory has any children
</li>
</ul>
</li>
</ul>
The extension would help those who mistakenly create a file instead of a directory or vise versa and have to delete, make a new one, and potentially type the full name of the file or directory again. With this extension, it is possible to right-click and jump between file type and directory type.
Implement
Tools
Init
in your preferred destination execute:
? What type of extension do you want to create? New Extension (TypeScript)
? What’s the name of your extension? Oops
? What’s the identifier of your extension? oops
? What’s the description of your extension? BLANK
? Initialize a git repository? Yes
? Which package manager to use? yarn
Procedure
We need two main functionality in this project:
We need two main validations before each operation:
We need to use VS Code FileSystem API extensively. One of the best places to find good examples of use cases for VS Code Extensions in VS Code Extension Samples repositories. It has a wide variety of different examples and uses different APIs of VS Code. One of those examples is the tree view example which includes one file we can utilize in our extension. It is fileExplorer.ts and covers all necessary FileSystem APIs we need such as delete directory, delete the file, create a new directory and, create a new file. we copy over this file to our src directory. we also need to add @types/rimraf and @types/mkdirp to devDependencies, and mkdirp and rimraf to dependencies in order to enable us to make a new directory and remove a directory.
Contribution
We start with editing our package.json file. We have used an extension manifest for filling this file.
We define an activation event for our extension. Activation event is:
https://code.visualstudio.com/api/references/activation-events
whenever oops.swap been invoked, our extension becomes active. Then we have to fill out contributes section of package.json:
In the command section, we have defined command and title for our extension and also added its explorer/context menu, these are called Contribution Points. Ours is in explorer context menu and is located in the cutcopypaste group of the menu is sorted at the end of the group because of @999. This will give us File ↔ Folder menu item in the context menu:
Next, in src/extension.js we start to write the actual functionality of our extension. First, we implement the functionality of the file to the folder:
It’s an async function which first reads the given file URI content. We should do this to be sure we would not cause messing with people’s code and only convert those files that are actually empty. the simplest approach is to read the content and then check the length of it like:
But this approach leaves us by reacting to file with return/enter character as not empty files. This can be a particular case with lots of users who have enabled to enter a return/enter at the end of all files at the save. We don’t want that behavior. So we have to define our own definition of emptiness.
First, we should note that VS Code FS API gives back content of a file character by character in an Array of ASCII code of corresponding characters. We that in mind, we can call a file empty if and only if all characters presented in a file are:
<td>
<strong>ASCII Code</strong>
</td>
<td>
9
</td>
<td>
10
</td>
<td>
13
</td>
<td>
32
</td>
Then we can check if every character in a file is one of the above ASCII codes:
isEmpty is going to be true if every character in the given content are one of four specified characters and would be false if there is any other character in the file.
The very last step for fileToFolder functionality is to do the actual swap between file and folder:
Now that we are done with this functionality we can move to implement folderToFile functionality. The first step is to check if the directory is empty:
if children.length is not zero, we have a not empty directory and we should abort function, otherwise, we are good to go. Now, we can initial a new file with the same URI of the folder, delete that folder and write a new file:
The only note in the above code is that we are setting content to empty object of type Uint8Array and we should pass create and overwrite parameters to writeFile method.
Our extension is almost ready and we a full implementation of all functionality we planned to have:
From the activity center select and execute Run Extension and you should see your extension in a new VS Code window.
Testing
As we have implantation for our extension, it is always good to write corresponding testing suite cases for our codes. We start things with editing src/test/suite/extension.test.js file.
In case of testing, we should make sure these four behavior are implemented as expected:
First, we need to include the actual extension file in our test file, we add the following import at the top of our test file:
Next, we need an actual environment to test these functionalities, and by the environment, I mean a bunch of files and folders that we can run tests against them. So we create one:
In this example environment, we have:
We import our test environment into our test file along fs and path libraries:
The first test case is to convert folder to file and we need oops_file.js to be converted to a file. So we need its URI:
Then we need to run folderToFile function on the folder and assert it is converted to a file.
So far so good, but there is one caveat here, first we need to convert back this process in order to keep running tests without constantly fix our test environment directory. for our extension, it is as easy as calling fileToFolder:
The second caveat for this particular test case is that we want to run these test cases using GitHub actions later on. We want to share this project with other developers, possibly. Still, an empty folder would not be committed into our git repository without having anything in it, and our folderToFile function won’t run when it has any children in it. So what should we do? We can fix by adding a .gitkeep file into this folder, and then in our test case, we move this file to the root of the testing environment directory, and at the end of the test, we move back it into its original place. Like this:
With that put aside, it’s time to move to the next test case. 2nd test case is ensuring we won’t convert a not empty directory to a file. If we do this, the user will lose information in that folder.
We get uri of the the not_empty_directory directory and call folderToFile method on it. Now we can assert that the given directory is still a directory and the only file in that folder directory_with_children is still a file.
The next test would be testing to see if we can change the file to a folder. For that, we would run the following test:
The last test is to check if we would not be able to delete a file which is not empty:
From activity center run Extension Tests and you should all tests passed.
Test Automation
This step is optional, but we can set GitHub Actions to run our tests every time we push. create a ci.yml file in .github directory with the following content:
In this file, we are telling GitHub action to listen to pushes on branch master, and if one happened, executes the defined job. In the job, we basically set up to run yarn run test command, so we need node and we want it to be run on 3 different OSes, macOS, Ubuntu, and Windows.
Documentation
Our extension functionality is a test and ready and surely we can ship it now, but a software without any documentation can be only useful to the author of that software and would not go anywhere besides the author’s projects. Once I have read that you should put the same amount of time into the documentation as the same you invest in coding, so don’t underestimate documentation.
Having a GIF image in your readme for the extension can quickly deliver the main functionalities your extension is providing. If you already don’t have a GIF maker software, you can try GIPHY Capture for mac, ScreenToGif for Windows, or Peek for Linux. The final GIF can be placed in README.md a file, you can check mine at here. The saved gifs can be placed screenshots in folder or similar places.
Next in your README add more details about your extension, answer questions like whats is for? Who is it for? What features it offers? Also, add bug_report and feature_request template in your repository so any possible bug or feature would be in the same template, and it easier to maintain them. Read about the GitHub issue template here, and you should find similar documentation for other VCS platforms such as GitLab and BitBucket.
Final optional touches for documentation would be adding. CHANGELOG, CODE_OF_CONDUCT, and CONTRIBUTING. And also, we should always include a LICENSE file in our repositories. By adding a license file, we enable other potential contributors to use, change, and distribute our code.
Publish
With everything in place, it’s time to make our extension ready to be published. We start by adding .gitattributes to our file. In this file, we exclude any file that is not necessary to be included when an end-user uses our code. Those not necessary files can be a large screenshot, tests directory, and any file not required by the extension. You can read more about gitattributes in git documentation.
The next step in publishing our extension is to add a nice icon for it. I have gone with the following icon, nothing special is going on in my icon design but you can put more time into yours:
save your extension icon in the images directory and head to packages.json adjust it for our extension. in this file we would set extension manifest for our extension, refer to the documentation for further details, and also you can check the Oops packages.json file.
Our final step will be to create a publisher for Visual Studio Code Extension Market if we don’t have one and login afterward. VS Codde documentation has explained it in detail. We can now publish our extension by executing:
And after a few minutes, we would be live! 🎉
Conclusion
We have learned how to create an extension for Visual Studio Code, test it, and deploy it. The only remaining step in any software is to market it and introduce it to other people. You can do so by tweeting about it, especially during creation time, and/or create a blog post and release notes about each version of it. A software without any user is kind of abandon despite how well made it could be, so go out there and tell about what you were working on.
Even though Oops is a tiny extension and is not deep dive into Visual Code extension APIs, there is still room to grow by implementing some other possible features such as disabling option if file or folder could not be deleted or added keyboard shortcut. Of course, it might not be a vital requirement for this particular extension.
Lastly, you can check Visual Studio Code Documentation for learning more about extension development. Also, you can go to Oops GitHub repo for full implementation and start it if you liked it and let me know if you didn’t. You can reach out to me on Twitter via @AmirmasoudShey1.