How I Built It: The Anatomy of a VS Code Extension

Why I Built It

I built a VS Code Extension that deploys code to GitHub Pages. I’ve always wanted to build a VS code extension, but I never had a reason or enough time. Now that I work in DevRel at GitHub, I finally got the opportunity to do so! The Microsoft VS Code team runs a resume website workshop where participants deploy a resume built with HTML and CSS to GitHub Pages.

I collaborated with the VS Code team to create a VS Code Extension that enables you to quickly deploy your static web page (Jekyll or HTML) to GitHub Pages without leaving your IDE.

My two favorite things are making a positive impact and experimenting with technologies I haven’t used!

How it’s Built

Initial Set-Up

VS Code Generator

To set up a template for my VS Code Extension, I installed the VS Code Extension Generator and Yeoman with the command below:

npm install -g yo generator-code

VS Code Extension Anatomy

Essential VS Code Concepts

• Activation Events: events upon which your extension becomes active.
• Contribution Points: static declarations that you make in the package.json Extension Manifest to extend VS Code.
• VS Code API: a set of JavaScript APIs that you can invoke in your extension code.

Extension Config Files

A VS Code extension includes these three configuration files:

• Tasks.json defines VS Code Tasks within your project. For my particular use case, I didn’t need to touch this file.
• tsconfig.json is a file in a directory that indicates the use of TypeScript in a project.
• launch.json configures VS Code Debugging. Although I didn’t update this section, Burke Holland did update this file. He added the code so that this extension could run when folks use Visual Studio Code as an editor in the browser.

Extension Manifest

The extension manifest is a package.json file. It includes scripts, devDependencies, a VS Code publisher, VS Code activationEvents, and VS Code contributes. In the screenshot below, I use the contributes to define my command called “extension.deployToGitHubPages”.

Extension Entry File

The entry point to my VS Code extension is called extension.js. In this entry file, I imported two classes that I created: credentials and repositories. The credentials file handles authentication so that the GitHub API can gain access to the user’s repositories. The repositories file fetches the user’s repositories and posts the chosen repository to a GitHub Page.

Interacting with GitHub

Authentication

I needed an access token to make API calls to retrieve repositories and deploy the code to GitHub Pages. I generated a new access token for each session using the vscode.authentication object. The getSession method attached to that object returns an access token. Note that GitHub’s access tokens have different levels of permissions called scopes. I need the token for my application to have access to the user, repository, and workflow.

VS Code QuickPick

The vscode.QuickPick API, enabled me easily collect user input or let the user make a selection from multiple options.

• Showing a list of options - The extension makes a GET request to retrieve a list of the 10 most recently created repositories and load those options into the QuickPick dialog.
• Responding to the user’s selection - The extension makes a POST request to publish the chosen repository to GitHub Pages based on the user’s choice.

Deploying to GitHub Pages

To deploy to GitHub Pages, I made an API call with Octokit. The API call, as mentioned above, is a POST request that takes the user’s login, selected repository, and default branch. If successful, the application will respond with a message stating that your GitHub Actions is building and deploying your site.

How to Use It

I wrote about using the GitHub extension in this blog post.

Open to Contributions

Honestly, I didn’t invest as much time as I wanted into creating this extension. There’s room for improvement. I’m open to contributions in helping me improve my README, improving the workflow, and my use of the any keyword is embarrassing. Feel free to open up an issue and a pull request in this repository: https://github.com/blackgirlbytes/vscodeextension-deploy-to-gh-pages

Tell me about an open source project you maintain or contribute to in the comments below!