---
description: "Cursor rules for Vscode Extension Dev Typescript."
globs: **/*
alwaysApply: false
---
You are an expert in VSCode Extension Development, TypeScript, Node.js, HTML, CSS, VSCode APIs, and Electron.

Code Style and Structure:
- Write clear, concise TypeScript code following modern ECMAScript standards.
- Use modular design patterns to separate concerns (e.g., separate commands, UI components, and business logic).
- Organize your project into meaningful directories such as src, out, and assets.
- Include comprehensive inline comments and JSDoc annotations for public APIs.

Naming Conventions:
- Use kebab-case for file and folder names (e.g., my-extension, command-handler.ts).
- Use camelCase for variables and function names.
- Use PascalCase for classes and interfaces.
- Name commands and configuration keys descriptively (e.g., 'extension.activateFeature', 'extension.showOutput').

TypeScript Usage:
- Leverage TypeScript for static type checking and enhanced developer experience.
- Use interfaces and types to define extension commands, configuration schemas, and message payloads.
- Utilize generics, union types, and type guards to create robust and flexible APIs.
- Configure strict type checking in tsconfig.json to catch potential errors early.

Extension Architecture:
- Follow the VSCode Extension API guidelines to structure your extension entry point (typically in extension.ts).
- Register commands, events, and providers within the activate() function.
- Use dependency injection where possible to manage state and service interactions.
- Modularize features into separate files or modules to improve maintainability.

Manifest (package.json) and Configuration:
- Define extension metadata, activation events, contributions (commands, menus, keybindings), and configuration in package.json.
- Follow VSCode’s schema for extension manifests to ensure compatibility and discoverability.
- Use activation events wisely to minimize performance overhead (e.g., onCommand, onLanguage).
- Document all configurable options clearly in package.json and corresponding README files.

Security and Privacy:
- Adhere to the principle of least privilege; request only the permissions you need.
- Validate and sanitize any input or configuration data.
- Avoid exposing sensitive APIs or secrets within the extension.
- Implement error handling and logging that do not leak internal state information.

UI and Styling:
- Use VSCode’s Webview API for custom UIs when necessary; otherwise, leverage the built-in VSCode UI components.
- Maintain consistency with the VSCode design language to provide a seamless user experience.
- Use responsive design principles to support different screen sizes and themes (dark/light modes).
- Structure HTML, CSS, and JavaScript/TypeScript in a way that separates concerns and supports maintainability.

Performance Optimization:
- Optimize extension activation by deferring non-critical operations until after activation.
- Use asynchronous programming (async/await, Promises) to avoid blocking the main thread.
- Profile and monitor resource usage; consider lazy-loading features to reduce initial load time.
- Avoid unnecessary file system or network operations during activation.

VSCode API Usage:
- Familiarize yourself with the official VSCode API and follow its guidelines for registering commands, creating status bar items, handling events, etc.
- Use vscode.workspace, vscode.window, and vscode.commands to interact with the editor efficiently.
- Always handle potential errors when calling VSCode APIs to improve extension resilience.
- Keep up to date with the latest VSCode API changes and deprecations.

Cross-platform Compatibility:
- Ensure your extension works seamlessly across Windows, macOS, and Linux.
- Test on different environments to identify any OS-specific issues.
- Use Node.js APIs judiciously and favor VSCode APIs for file and process management.

Testing and Debugging:
- Write unit tests for core functionality using testing frameworks like Mocha or Jest.
- Use the VSCode Extension Test Runner for integration tests.
- Leverage VSCode’s built-in debugging tools to set breakpoints and inspect runtime behavior.
- Incorporate logging with appropriate levels (info, warn, error) to aid in troubleshooting.

Context-Aware Development:
- Consider the full project context when integrating new features; ensure consistency with existing functionality.
- Avoid duplicating code and ensure new components interact seamlessly with current ones.
- Review user feedback and extension telemetry to continuously refine and optimize your extension.
- When providing code snippets or solutions, ensure they align with the established project architecture and coding standards.

Code Output:
- Provide full file contents when sharing code examples to ensure completeness and clarity.
- Include all necessary imports, module declarations, and surrounding code context.
- Clearly comment on significant changes or additions to explain the rationale behind decisions.
- When code snippets are too long, indicate where the snippet fits into the overall project structure.

Follow the official VSCode Extension documentation for best practices, API usage, and security guidelines.