VS Code Extension Template
A minimal, reusable template for building VS Code extensions with strict TypeScript,
native UX, and an OpenSpec workflow. Layout: L0 (single-package minimal).
When a project grows and needs a Webview or a separate UI package, follow the
L0 → L1 → L2 → L3 upgrade path in AGENTS.md.
Prerequisites
- Node.js ≥ 18.18
- pnpm ≥ 11 (
npm i -g pnpm or use Corepack)
- VS Code ≥ 1.93 (matches
engines.vscode)
Quick start
pnpm install
pnpm run verify # typecheck + lint + format:check + build
Open the folder in VS Code and press F5 to launch the Extension Development Host.
Edit src/extension.ts to add behavior.
Scripts
| Script |
What it does |
pnpm run typecheck |
tsc --noEmit |
pnpm run lint |
eslint . (typescript-eslint type-checked + prettier compat) |
pnpm run lint:fix |
eslint . --fix |
pnpm run format |
prettier --write . |
pnpm run format:check |
prettier --check . |
pnpm run build |
node esbuild.config.mjs → dist/extension.js |
pnpm run watch |
esbuild watch mode |
pnpm run package |
vsce package → <name>-<version>.vsix |
pnpm run verify |
typecheck && lint && format:check && build |
Troubleshooting
pnpm run fails with "Aborted removal of modules directory"
This is a known pnpm 11 behaviour: every script run triggers a deps check that
needs network access and a TTY. To skip the check, set the env var:
export pnpm_config_verify_deps_before_run=false
Add to ~/.zshrc (or ~/.bashrc) to make it permanent.
The setting cannot go in .npmrc because pnpm 11 excludes
verify-deps-before-run from project-level config (it is treated as install-affecting).
Customizing for your extension
- Rename: edit
name, displayName, description in package.json. Pick a
displayName that's unique on the Marketplace before publishing (see AGENTS.md).
- Add commands: register in
contributes.commands in package.json, implement in
src/extension.ts.
- Add native UI: prefer
TreeView, QuickPick, ThemeIcon, status bar, etc.
(see AGENTS.md UI section) before reaching for a Webview.
- Add a Webview: when the UI outgrows native surfaces, follow the L0 → L1 upgrade
in
AGENTS.md — typically renaming src/webview.ts and adding a webview/ sibling.
Layout
src/ host extension (TypeScript)
docs/ARCH.md mermaid architecture diagram
openspec/ spec-driven change workflow
media/ put `icon.png` here before publishing
dist/ esbuild output (gitignored)
Spec-driven development
This template ships with one OpenSpec capability: template-overview.
Future capability changes go through openspec/changes/<name>/ with proposal, specs,
design, and tasks.
# (requires the openspec CLI)
openspec new change <name>
# ...edit the four artifacts...
openspec validate <name> --strict
License
Apache-2.0. See LICENSE.
