Vscode Extension Dev TypeScript

Cursor-Regel für VS-Code-Extensions in TypeScript: API-Konventionen und Projektstruktur.

Original-Beschreibung der Autoren: Cursor rules for Vscode Extension Dev Typescript.

Die Regel

---
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.

So nutzt du sie

Die Regel kopieren (Button oben) oder als Datei herunterladen und im Projekt unter .cursor/rules/ ablegen — Cursor lädt sie beim nächsten Start automatisch. Ältere Cursor-Versionen lesen alternativ eine einzelne .cursorrules-Datei im Projektstamm; dort einfach den Regel-Text ohne den Kopfblock zwischen den ----Zeilen einfügen.

Der Regel-Text ist englisch — Cursor versteht ihn unabhängig von der Sprache, in der Sie mit dem Editor chatten.

Im Detail

Diese Regel richtet sich an die Entwicklung von VS-Code-Erweiterungen mit TypeScript und gibt Konventionen für die VS-Code-Extension-API vor, etwa zu Activation Events, Command-Registrierung und dem üblichen Projektaufbau mit package.json-Contributes. Nützlich ist das, weil die Extension-API eigene Muster hat (Disposables, Kontext-Objekt, Manifest-Deklarationen), die sich von normaler TypeScript-Anwendungsentwicklung unterscheiden und ohne Kontext leicht falsch umgesetzt werden. Für Entwickler, die erstmals eine VS-Code-Extension bauen oder mehrere Extensions parallel pflegen, spart das Einarbeitungszeit. Für reine Web- oder Node-Projekte ohne Extension-Bezug ist die Regel nicht relevant.

Praxis-Tipp

Beim Anlegen neuer Befehle nutzen, z. B. „Registriere einen neuen VS-Code-Command, der den aktuell markierten Text formatiert, inklusive Manifest-Eintrag“.

Siehe auch

• Ankra CLI

Lizenz & Quelle

• Lizenz: CC0 1.0
• Quelle: PatrickJS/awesome-cursorrules (GitHub)

Lade …