As I’ve been using Windsurf as my primary code editor, I encountered a situation where the vs-picgo extension wasn’t available in the Windsurf marketplace. This necessitated the need to manually package the extension from its source code. This guide documents the process of generating a VSIX file for VS Code extensions, which can then be installed manually in compatible editors like Windsurf.

In this guide, I’ll walk you through the process of generating a VSIX file from a VS Code extension’s source code. We’ll use the popular vs-picgo extension as an example.

Prerequisites

Before we begin, make sure you have the following installed:

• Node.js (version 12 or higher)
• npm (comes with Node.js)

Step 1: Install Required Tools

First, we need to install two essential tools:

• yarn: A package manager that will handle our dependencies
• vsce: The VS Code Extension Manager tool that creates VSIX packages

1
2
3
4
5

# Install Yarn globally
sudo npm install -g yarn

# Install vsce globally
sudo npm install -g @vscode/vsce

Step 2: Prepare the Project

1. Clone or download the extension source code:

   1 2	git clone https://github.com/PicGo/vs-picgo.git cd vs-picgo

2. Install project dependencies:

   1	yarn install

This command will:

• Read the package.json file
• Install all required dependencies
• Create or update the yarn.lock file

Note: The yarn.lock file is important! Don’t delete it as it ensures consistent installations across different environments.

Step 3: Build the Extension

Build the extension using the production build command:

1

yarn build:prod

This command typically:

• Cleans the previous build output
• Compiles TypeScript/JavaScript files
• Bundles all necessary assets
• Creates the dist directory with the compiled code

In vs-picgo’s case, the build process:

1. Uses esbuild for fast bundling
2. Creates both extension and webview bundles
3. Generates source maps (disabled in production)
4. Optimizes the code for production use

Step 4: Package the Extension

Finally, create the VSIX file:

1

vsce package

This command:

1. Runs any pre-publish scripts defined in package.json
2. Validates the extension manifest
3. Packages all required files into a VSIX file
4. Names the file based on the extension’s name and version (e.g., vs-picgo-2.1.6.vsix)

The resulting VSIX file will contain:

• Compiled JavaScript files
• Assets (images, CSS, etc.)
• Extension manifest
• Documentation files
• License information

What’s Inside the VSIX?

The VSIX file is essentially a ZIP archive with a specific structure. For vs-picgo, it includes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

vs-picgo-2.1.6.vsix
├─ [Content_Types].xml 
├─ extension.vsixmanifest 
└─ extension/
   ├─ LICENSE.txt
   ├─ changelog.md
   ├─ logo.png
   ├─ package.json
   ├─ package.nls.json
   ├─ readme.md
   └─ dist/
      ├─ extension.js
      └─ webview/
         ├─ index.css
         └─ index.js

Installing the Extension

You can install the generated VSIX file in VS Code or any compatible editor by:

1. Opening VS Code/Windsurf/Cursor …
2. Going to the Extensions view
3. Clicking the “…” menu (More Actions)
4. Selecting “Install from VSIX…”
5. Choosing your generated VSIX file

Troubleshooting

If you encounter any issues:

1. Missing dist directory error:

   • This is normal on first build
   • The build process will create it automatically

2. Dependency errors:

   • Run yarn install again
   • Check if you’re using the correct Node.js version

3. VSIX packaging fails:

   • Verify your package.json is valid
   • Ensure all required files are present
   • Check the extension manifest for errors

Conclusion

Building a VS Code extension VSIX file is straightforward once you have the right tools installed. The process mainly involves installing dependencies, building the source code, and packaging everything into a VSIX file.

Remember to keep your yarn.lock file and always build in production mode before packaging to ensure the best performance and smallest file size for your users.

Happy extension building! 🚀