Build Your First VS Code Extension and Ship It to the Marketplace

What you'll build

A working VS Code extension that adds a "Hello World" command to the Command Palette, published live on the Visual Studio Marketplace under your own publisher ID.

Prerequisites

• Node.js 20.5+ (nodejs.org). The scaffolder requires Node ≥ 20.5, the publishing tool requires Node ≥ 20. Verified against generator-code 1.12.0 and @vscode/vsce 3.9.2.
• VS Code, current stable, updated recently. The generated project targets the latest Extension API.
• Git on your PATH (the generator offers to init a repo).
• A free Microsoft account, for the Marketplace publisher and the Azure DevOps access token.
• Any OS. Commands are identical on macOS, Linux, and Windows; keyboard shortcuts below list both.

1. Scaffold the extension

Run the official Yeoman generator without installing anything globally:

npx --package yo --package generator-code -- yo code

Answer the prompts:

Two files matter. package.json is the extension manifest: contributes.commands declares the Hello World command so VS Code can show it before your code ever loads. src/extension.ts is the runtime: its activate() function registers the handler that runs when the command fires.

2. Run and debug it

With the project open in VS Code, press F5 (or Run > Start Debugging). A second window opens, the Extension Development Host, with your extension loaded. In that window, open the Command Palette with Cmd+Shift+P (Ctrl+Shift+P on Windows/Linux) and run Hello World.

A notification appears in the bottom-right corner:

Hello World from HelloWorld!

Change the message string in src/extension.ts, then restart debugging with Cmd+Shift+F5 (Ctrl+Shift+F5) and run the command again to see your edit. That's the whole dev loop.

3. Create a publisher and an access token

Every Marketplace extension belongs to a publisher. Go to marketplace.visualstudio.com/manage, sign in with your Microsoft account, click Create publisher, and pick an ID. The ID is permanent and must be unique; the display name you can change later.

Next, the token vsce uses to authenticate. Go to dev.azure.com, open User settings > Personal access tokens > New Token, and set:

• Organization: All accessible organizations
• Scopes: Custom defined, then Marketplace > Manage

Copy the token somewhere safe; it's shown once. One heads-up: Microsoft retires global PATs on December 1, 2026, and recommends Microsoft Entra ID auth for automated publishing. For a first manual publish, a PAT is still the documented path.

4. Prepare the manifest

Three edits before publishing, or vsce will stop you:

1. Add your publisher ID to package.json:

"publisher": "your-publisher-id",

2. Replace the template text in README.md with a real description. vsce refuses to package a README it recognizes as boilerplate.
3. Optional but recommended: add a repository field pointing at your GitHub repo. Without it, vsce errors unless you pass --allow-missing-repository.

5. Publish

npm install -g @vscode/vsce
vsce login your-publisher-id

Paste the PAT when prompted, then:

vsce publish

vsce compiles the extension, packages it, and uploads it. Prefer to inspect first? vsce package produces a .vsix file you can install locally (Extensions view > ... menu > Install from VSIX) or upload manually on the manage page.

Verify it works

vsce login confirms the token before you publish:

The Personal Access Token verification succeeded for the publisher 'your-publisher-id'.

After vsce publish reports the published version, your extension lives at:

https://marketplace.visualstudio.com/items?itemName=your-publisher-id.helloworld

The Marketplace runs a short validation pass, so allow a few minutes before the page and search results appear. Final check: in a fresh VS Code window, search the Extensions view for your extension name and install it. Run Hello World from the Command Palette; you should get the same notification as in step 2, now from the installed build.

Troubleshooting

It seems the README.md still contains template text. Make sure to edit the README.md file before you package or publish your extension. You skipped step 4.2. Replace the generated README content with your own and rerun.

A 'repository' field is missing from the 'package.json' manifest file. Use --allow-missing-repository to bypass. Add a repository field ("repository": {"type": "git", "url": "https://github.com/you/helloworld"}) or pass the flag.

The Personal Access Token verification has failed. Almost always a token misconfiguration: the organization must be All accessible organizations (not a single org) and the scope must be Marketplace > Manage. Expired tokens fail the same way; create a new one and vsce login again.

Missing extension "publisher" in package.json Add the publisher field from step 4.1. Use the publisher ID, not the human-friendly display name; vsce rejects the latter with a separate "Invalid extension publisher" error.

Next steps

Swap the notification for something real: the contribution points reference covers menus, keybindings, settings, and language features. When your extension grows past a few files, bundle it with esbuild so it loads fast. For releases after the first, vsce publish patch bumps the version and publishes in one step, and the publishing guide documents CI setups with Entra ID so you can ship from GitHub Actions without a PAT.