DEV Community

Cover image for Build Your First VSCode Extension in 15 Minutes (Complete Beginner's Guide)
Dr. R. Vinob Chander
Dr. R. Vinob Chander Subscriber

Posted on • Edited on • Originally published at Medium

Build Your First VSCode Extension in 15 Minutes (Complete Beginner's Guide)

#vscode #extensions #tutorial #beginners

Have you ever used a VSCode extension and thought, "I wonder how they built this?" Well, today's your lucky day! I'm going to walk you through creating your very first VSCode extension from scratch. By the end of this tutorial, you'll have a working extension that you can debug and test immediately.

Don't worry if you're new to extension development – I'll explain everything step by step, just like a senior engineer teaching you the ropes.

What We're Building

We're going to create a simple "Hello World" extension called "Smart Developer Tools". It might sound basic, but this foundation is exactly what every successful VSCode extension starts with. Think of it as your gateway into the world of editor customization!

Prerequisites

Before we dive in, make sure you have:

  • VSCode installed (obviously! 😄)
  • Node.js and npm
  • Basic knowledge of TypeScript/JavaScript

Ready? Let's build something awesome!

Step 1: Setting Up Your Project

First, let's create our workspace:

mkdir Smart_Developer_Tools
cd Smart_Developer_Tools
npm init -y
Enter fullscreen mode Exit fullscreen mode

Step 2: The Heart of Your Extension - package.json

This file is like your extension's birth certificate. It tells VSCode everything it needs to know about your extension:

{
  "name": "smart-developer-tools",
  "displayName": "Smart Developer Tools",
  "description": "Your intelligent coding companion",
  "version": "0.0.1",
  "engines": {
    "vscode": "^1.74.0"
  },
  "categories": ["Other"],
  "activationEvents": [],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "smart-developer-tools.helloWorld",
        "title": "Smart Developer: Hello World"
      }
    ]
  },
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./"
  },
  "devDependencies": {
    "@types/vscode": "^1.74.0",
    "@types/node": "16.x",
    "typescript": "^4.9.4"
  }
}
Enter fullscreen mode Exit fullscreen mode

What's happening here?

  • name: Your extension's unique identifier (like a username)
  • displayName: What users see in the marketplace
  • main: Points to your compiled JavaScript file
  • contributes.commands: Registers your commands with VSCode
  • The command ID smart-developer-tools.helloWorld will be crucial later!

Step 3: TypeScript Configuration

Create a tsconfig.json file to tell TypeScript how to compile your code:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2021",
    "outDir": "out",
    "rootDir": "src",
    "lib": ["ES2021"],
    "sourceMap": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  },
  "exclude": ["node_modules", ".vscode-test"]
}
Enter fullscreen mode Exit fullscreen mode

Why these settings?

  • strict: true: Catches bugs early (trust me, you want this!)
  • sourceMap: true: Makes debugging a breeze
  • outDir: "out": Keeps compiled files organized

Step 4: The Magic Happens - extension.ts

Create a src folder and add extension.ts:

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    console.log('Smart Developer Tools is now active! 🚀');

    let disposable = vscode.commands.registerCommand('smart-developer-tools.helloWorld', () => {
        vscode.window.showInformationMessage('Hello from Smart Developer Tools! 🎯 Ready to code smarter?');
    });

    context.subscriptions.push(disposable);
}

export function deactivate() {}
Enter fullscreen mode Exit fullscreen mode

Let me break down this code:

  1. The activate function - This is called when your extension starts up. It's like the main() function for your extension.

  2. Command registration - We're telling VSCode: "Hey, when someone runs the command smart-developer-tools.helloWorld, execute this function!"

  3. The Disposable pattern - VSCode uses this for cleanup. Think of it as putting your toys away when you're done playing.

  4. The deactivate function - Called when your extension shuts down. Usually empty, but good to have for cleanup if needed.

Step 5: Debug Configuration - The Missing Piece

Create .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Run Extension",
            "type": "extensionHost",
            "request": "launch",
            "args": [
                "--extensionDevelopmentPath=${workspaceFolder}"
            ],
            "outFiles": [
                "${workspaceFolder}/out/**/*.js"
            ]
        }
    ]
}
Enter fullscreen mode Exit fullscreen mode

This configuration is what makes the magic Cmd+Shift+D debugging possible!

Step 6: Essential Project Files

Create .gitignore:

out
node_modules
.vscode-test
Enter fullscreen mode Exit fullscreen mode

Create .vscodeignore:

.vscode
.vscode-test
src
.gitignore
tsconfig.json
Enter fullscreen mode Exit fullscreen mode

Create a basic README.md:

# Smart Developer Tools

Your intelligent coding companion for VSCode.

## Features

- Quick Hello World command to test the extension

## Usage

1. Press `Cmd+Shift+P` (or `Ctrl+Shift+P` on Windows/Linux)
2. Type "Smart Developer: Hello World"
3. See the magic happen!
Enter fullscreen mode Exit fullscreen mode

Step 7: The Moment of Truth - Testing!

Now for the exciting part:

  1. Compile your TypeScript: 
   npm run compile
Enter fullscreen mode Exit fullscreen mode

  1. Start debugging: Press Cmd+Shift+D (or Ctrl+Shift+D)

  2. Launch Extension Development Host: Click the green play button or press F5

  3. Test your command: In the new VSCode window, press Cmd+Shift+P and type "Smart Developer: Hello World"

  4. Celebrate! 🎉 You should see "Hello from Smart Developer Tools! 🎯 Ready to code smarter?" in the bottom-right corner.

Understanding the Architecture

Let me explain what just happened under the hood:

The Extension Lifecycle

  1. Activation: VSCode reads your package.json, sees the activation events, and calls your activate() function
  2. Command Registration: Your extension tells VSCode about available commands
  3. User Interaction: When a user runs a command, VSCode routes it to your registered callback
  4. Cleanup: When the extension deactivates, VSCode calls your cleanup functions

The Build Process 

src/extension.ts → [TypeScript Compiler] → out/extension.js → [VSCode loads it]
Enter fullscreen mode Exit fullscreen mode

Why This Pattern Works

  • Separation of Concerns: Configuration (package.json) separate from logic (extension.ts)
  • Type Safety: TypeScript catches errors at compile time
  • Resource Management: Disposable pattern prevents memory leaks
  • Developer Experience: Hot reloading during development

What's Next?

Congratulations! You've just built your first VSCode extension. This simple foundation can grow into something amazing:

  • Add more commands for different functionality
  • Create custom views with TreeView providers
  • Build webview panels for rich UI experiences
  • Integrate with language servers for advanced code features
  • Add configuration options for user customization

Key Takeaways

  1. Every extension starts simple - Even complex extensions began with a "Hello World"
  2. The package.json is crucial - It's your extension's contract with VSCode
  3. TypeScript is your friend - The type safety catches bugs early
  4. Debugging is built-in - VSCode makes extension development surprisingly pleasant

Final Thoughts

Building VSCode extensions might seem intimidating at first, but as you can see, the basics are quite approachable. The extension ecosystem is incredibly powerful, and now you have the foundation to tap into it.

Start small, experiment often, and most importantly – have fun building tools that make your coding life better!

What will you build next? Drop me a comment below – I'd love to hear about your extension ideas!

Happy coding! 🚀

Found this tutorial helpful? Follow me for more developer content and tutorials!

🚀 Writing a new project? Grab my free/₹99 Developer README Kit here

Top comments (0)