home / skills / atman-33 / skills / vscode-webview-ui

vscode-webview-ui skill

safe

/skills/vscode-webview-ui

This skill helps you develop React-based VS Code Webview UI features with guidance on structure, messaging, styling, and testing for extensions.

npx playbooks add skill atman-33/skills --skill vscode-webview-ui

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.4 KB

---
name: vscode-webview-ui
description: Develop React applications for VS Code Webview surfaces. Use when working on the `webview-ui` package, creating features, components, or hooks for VS Code extensions. Includes project structure, coding guidelines, and testing instructions.
---

# VS Code Webview UI

## Overview

This skill assists in developing the React application that powers VS Code webview surfaces. It covers the `webview-ui` workspace, which is bundled with Vite and communicates with the extension host via the `bridge/vscode` helper.

## Project Structure

The `webview-ui` package follows this structure:

```
webview-ui/
├── src/
│   ├── components/        # Shared visual components reused across features
│   │   └── ui/            # shadcn/ui component library
│   ├── hooks/             # Shared React hooks
│   ├── features/
│   │   └── {feature}/
│   │       ├── index.tsx  # Feature entry component rendered from routing
│   │       ├── components/# Feature-specific components
│   │       └── hooks/     # Feature-specific hooks
│   ├── bridge/            # Messaging helpers for VS Code <-> webview
│   └── index.tsx          # Runtime router that mounts the selected feature
├── public/                # Static assets copied verbatim by Vite
├── vite.config.ts         # Vite build configuration
└── README.md
```

## Coding Guidelines

- **Shared Modules**: Prefer shared modules under `src/components` and `src/hooks` before introducing feature-local code.
- **Feature Boundaries**: Add feature-only utilities inside the nested `components/` or `hooks/` directories to keep boundaries clear.
- **Styling**: Keep styling in Tailwind-style utility classes (see `src/app.css` for base tokens) and avoid inline styles when reusable classes exist.
- **Messaging**: Exchange messages with the extension via `vscode.postMessage` and subscribe through `window.addEventListener('message', …)` inside React effects.
- **Configuration**: When adding new steering or config references, obtain paths through the shared `ConfigManager` utilities from the extension layer.

## Testing & Quality

- **Integration Tests**: Use Playwright or Cypress style integration tests if adding complex interactions (tests live under the repo-level `tests/`).
- **Pre-commit Checks**: Run `npm run lint` and `npm run build` before committing to ensure TypeScript and bundler checks pass.

Overview

This skill helps you develop React applications that run inside VS Code webview surfaces. It focuses on the webview-ui package, bundled with Vite, and explains the project layout, coding conventions, and testing guidance. Use it to create features, components, and hooks that communicate reliably with the extension host.

How this skill works

The skill inspects and documents the webview-ui workspace structure and the recommended patterns for shared components, feature boundaries, and messaging. It explains using the bridge/vscode helper to post and receive messages between the webview and extension host, and it guides how the runtime router mounts feature entry points. It also outlines tooling and testing steps to keep builds and types consistent.

When to use it

When adding a new UI feature or page to the webview-ui workspace.
When creating reusable UI components or shared hooks for multiple features.
When implementing message exchanges between the webview and the extension host.
When introducing build or configuration changes that affect the Vite bundle.
When writing integration tests for complex interactions in the webview.

Best practices

Prefer shared modules under src/components and src/hooks before creating feature-local code.
Keep feature-only utilities inside feature-specific components/ or hooks/ subfolders to preserve clear boundaries.
Use Tailwind-style utility classes and base tokens from src/app.css; avoid inline styles for reusable UI.
Send messages via vscode.postMessage and listen with window.addEventListener('message', …) inside React effects to ensure lifecycle safety.
Run npm run lint and npm run build before committing to catch TypeScript and bundler issues.

Example use cases

Add a new editor panel feature: create feature/{name}/index.tsx, feature-specific components, and hooks, then register routing entry in index.tsx.
Create a shared component (e.g., settings form) under src/components/ui and reuse it across multiple features.
Implement two-way communication: use bridge/vscode helpers to post commands to the extension and subscribe to incoming state updates in a useEffect hook.
Write Playwright or Cypress integration tests under tests/ to validate complex UI flows before merging.

FAQ

How should I structure feature files?

Place entry point index.tsx at feature/{name}/, nested components in components/, and feature-only hooks in hooks/. Prefer shared modules for anything reusable across features.

How do I send and receive messages safely?

Use vscode.postMessage to send messages and subscribe with window.addEventListener('message', handler) inside a useEffect that cleans up the listener to avoid leaks.