Building Vscode Extension

We built this skill because the VS Code Extension API is a beast. You think you're writing a script, but you're entering a lifecycle management system. The official Extension Guides ^[1] cover a massive surface area, and that's precisely the problem. You aren't just dropping a file into a folder; you're managing activation events, extension contexts, disposables, and the delicate boundary between the extension host and the editor UI.

When you start a VS Code extension, you immediately run into the activation model. If your activationEvents are wrong, your extension either consumes memory constantly or fails to load when needed. You have to configure package.json with precise contributes blocks for commands, menus, and keybindings. You have to set up strict TypeScript configs that target the right Node.js versions without breaking the browser-like environment of webviews. And if you're pulling data, you're likely integrating GraphQL, which adds another layer of schema management and type generation on top of the extension lifecycle.

The API surface is vast. You might need to handle commands ^[4], create webviews ^[3], register test providers ^[5], manage telemetry ^[2], support web extensions ^[7], interact with source control ^[8], or even build notebook kernels ^[6]. Each of these requires specific patterns. Commands need proper context key handling. Webviews need secure content security policies and state restoration. Testing needs workspace-aware runners. Telemetry needs user-consent checks. Web extensions need sandboxed execution. Source control needs input box management. Notebooks need rich rendering.

Most engineers treat the extension scaffold as a throwaway. They copy a sample, tweak it, and ship. This works until you hit the edge cases: a memory leak from an unregistered disposable, a webview that loses state on editor reload, or a command that fires in the wrong context. We created this skill so you don't have to debug these issues from scratch. We provide the production-grade templates, validators, and references that turn a fragile hack into a maintainable extension.

What Bad Extension Architecture Costs You

Ignoring proper extension architecture isn't free. The cost shows up in hours, dollars, and user trust. When your activation events are misconfigured, you pay in support tickets. Users report that the extension "doesn't work" because it only activates on file open, not on folder open, or vice versa. You spend hours debugging why your command palette entries are missing, only to find you forgot to register them in the contributes.commands block correctly.

Memory leaks are the silent killer. Every event listener, timer, and disposable must be tracked. If you miss one, your extension holds onto references, bloating the extension host memory. At scale, this causes the editor to lag or crash. We've seen teams lose dozens of hours chasing down a single unregistered vscode.Disposable that kept a large GraphQL client alive in memory.

Webview state loss is another common pain point. If you're building a dashboard or a custom editor, you need to persist state across reloads. Without proper implementation, users lose their work every time they switch tabs. This erodes trust instantly. A user who loses data once will uninstall your extension and leave a bad review. The cost of a bad review is harder to quantify, but it's real. It kills adoption.

Telemetry violations can lead to privacy breaches. If you send telemetry without respecting user choices, you risk violating VS Code's privacy guidelines and potentially legal requirements. The Telemetry extension authors guide ^[2] is clear on this: you must enable telemetry explicitly and respect user settings. Skipping this check is a liability.

Security issues in webviews are also a risk. If you load external content without proper Content Security Policies (CSP), you expose users to XSS attacks. The Webview API ^[3] requires careful handling of src and csp. A misconfigured CSP can break functionality or open security holes.

Testing is often an afterthought, but it shouldn't be. The Testing API ^[5] allows users to discover and run unit tests in their workspace. If your extension doesn't integrate with this, you're forcing users to run tests manually or in isolation. This increases the chance of regressions and slows down development. We've seen teams spend hours writing custom test runners when the Testing API could have done the heavy lifting.

A Hypothetical Team's Struggle with Activation and Webviews

Imagine a team building a dashboard extension for their internal API. They start with a basic scaffold and add a webview ^[3] to display metrics. They use React for the UI and GraphQL for data fetching. Everything seems fine until they hit the edge cases.

First, they notice the webview loses state when the user switches tabs. They didn't implement state restoration, so the dashboard resets to defaults every time. They spend days debugging why their React state isn't persisting, only to realize they need to save the state in the extension context and restore it on activation.

Next, they register a command to refresh the dashboard. But the command fires even when the webview isn't focused. They didn't use context keys to scope the command to the active webview. Users get confused because the refresh action doesn't seem to do anything when they're editing code. They have to refactor the command registration to use when clauses in package.json.

They also add telemetry to track usage. But they forget to check user telemetry settings. They send data even when the user has disabled telemetry. This violates the Telemetry extension authors guide ^[2] and risks a privacy breach. They have to add a telemetry check to every data point, adding boilerplate and complexity.

Finally, they try to add tests. They write unit tests but run them manually. They miss a regression in the GraphQL schema validation, and the extension breaks in production. They realize they should have used the Testing API ^[5] to integrate tests into the workspace. They spend weeks refactoring their test setup to use the Testing API.

This scenario is common. The team spends weeks fixing issues that could have been prevented with proper scaffolding and validation. They end up with a hacky solution that's hard to maintain. If they had used a structured approach, they could have avoided these pitfalls. For example, comparing the extension model to building-chrome-extension reveals similarities in manifest structure, but VS Code's activation model is unique. Similarly, patterns in browser-extension-pack highlight the importance of service workers, which map to VS Code's activation events. If you're coming from building-wordpress-plugin development, the hook system offers parallels to VS Code's event-driven architecture. And for desktop apps, building-electron-desktop-app shares some IPC concepts that can inform your extension's design.

What Changes Once the Skill Is Installed

With this skill installed, the complexity is handled. You get production-grade templates that enforce best practices from day one. Your package.json includes proper activation events, contributes, and codegen hooks. Your tsconfig.json is strict and optimized for VS Code extension development and Node.js targets. Your codegen.ts is configured with the client preset, fragment masking, schema loading, and lifecycle hooks.

Validation ensures structural compliance. The validate.sh script checks your package.json structure and codegen.ts syntax using jq and grep. It exits non-zero on missing required fields or invalid config. This catches errors before you ship. The extension-schema.json defines required fields for package.json and codegen.ts, ensuring consistency across your project.

References provide canonical knowledge. The vscode-architecture.md file covers the VS Code extension lifecycle, activation events, extension context, and webview best practices. The graphql-codegen-integration.md file covers schema loading, client presets, hooks, directives, and type-safe resolver patterns. You don't have to search for this information; it's curated and ready to use.

Examples show production-grade patterns. The extension-activation.ts file demonstrates proper activate and deactivate functions with disposable registration. The webview-react.tsx file shows a React-based webview with proper icon handling and state management. You can copy these examples and adapt them to your needs.

Testing is built in. The run-validation.sh test suite executes validate.sh, asserts exit code 0 on valid input, and exit code 1 on modified/invalid input. This ensures your extension meets the required standards before you commit.

The scaffold.sh script bootstraps a new extension directory, copies templates, and initializes npm. You can start a new project in seconds with a solid foundation. The skill.md orchestrator defines the workflow, referencing all templates, scripts, validators, references, and examples. It guides you through the entire process, step by step.

What's in the Pack

• skill.md — Orchestrator skill that defines the workflow for building VS Code extensions with GraphQL Codegen integration. References all templates, scripts, validators, references, and examples.
• templates/package.json — Production-grade VS Code extension manifest with activation events, contributes, and codegen hooks.
• templates/tsconfig.json — Strict TypeScript configuration optimized for VS Code extension development and Node.js targets.
• templates/codegen.ts — GraphQL Codegen configuration grounded in Context7 docs: client preset, fragment masking, schema loading, and lifecycle hooks.
• scripts/scaffold.sh — Executable script that bootstraps a new extension directory, copies templates, and initializes npm.
• scripts/validate.sh — Validator that checks package.json structure and codegen.ts syntax using jq and grep. Exits non-zero on missing required fields or invalid config.
• references/vscode-architecture.md — Canonical knowledge on VS Code extension lifecycle, activation events, extension context, and webview best practices.
• references/graphql-codegen-integration.md — Curated Context7 reference covering schema loading, client presets, hooks, directives, and type-safe resolver patterns.
• examples/extension-activation.ts — Worked example of production-grade activate/deactivate functions with proper disposable registration.
• examples/webview-react.tsx — Worked example of a React-based webview with proper icon handling and state management.
• validators/extension-schema.json — JSON Schema defining required fields for package.json and codegen.ts to ensure structural compliance.
• tests/run-validation.sh — Test suite that executes validate.sh, asserts exit code 0 on valid input, and exit code 1 on modified/invalid input.

Stop Guessing, Start Shipping

You don't have to debug activation events, webview state loss, or telemetry violations. You don't have to write boilerplate for commands, menus, or keybindings. You don't have to search for best practices or risk shipping a fragile extension.

Install this skill and get a production-grade foundation. Your extensions will be validated, tested, and documented. You'll ship faster with fewer bugs. You'll build trust with your users.

Upgrade to Pro to install. Stop guessing, start shipping.