# UX Best Practices for Volar-based Language Servers

> [Docs Index](README.md) • [Repo README](../README.md) • [Telemetry](telemetry-and-observability.md) • [Error Handling](error-handling-and-resilience.md)

A language server lives inside the editor experience; thoughtful UX keeps users confident and productive. This guide focuses on user-facing behaviors—status messages, progress indicators, error notifications, settings UX, and documentation—for Volar integrations.

## Goals

1. **Transparency** – users know what the server is doing (diagnostics running, schema fetching, errors).
2. **Actionable feedback** – every warning/error tells the user how to resolve it.
3. **Control** – users can adjust settings, restart the server, or disable features when necessary.

## Status & Progress Indicators

### Initial Load / Heavy Tasks

- Use work-done progress for long-running operations (>500ms).

```ts
async function withProgress(title: string, task: () => Promise<void>) {
  const progress = await connection.window.createWorkDoneProgress();
  progress.begin(title);
  try {
    await task();
  } finally {
    progress.done();
  }
}
```

Examples:

- “Volar (JSON/YAML): Indexing workspace…”
- “Fetching schemas…”

### Idle Status

- Provide a summary command (VS Code command or Neovim RPC) that returns current workspace stats: number of open documents, diagnostics pending, schema cache status.
- Show a status bar entry with quick access to commands (e.g., “Volar: Ready • Diagnostics: 12”).

## Notifications

Use the right severity for notifications:

| Scenario | API | Message |
| --- | --- | --- |
| Non-blocking info (feature enabled) | `showInformationMessage` | “Volar Take Over Mode is now active.” |
| Recoverable issue | `showWarningMessage` | “Failed to fetch schema. Using cached version.” |
| Action required | `showErrorMessage` | “Invalid configuration: volarJsonYaml.schemas must be an array.” |

Tips:

- Provide action buttons: `showWarningMessage(msg, 'Retry', 'Open Settings')`.
- Limit frequency—use throttling so the same warning doesn’t appear repeatedly.

## Settings UX

### Documentation

- Publish a markdown file (e.g., `docs/configuration-and-projects.md`) describing every setting with default values and examples.
- If shipping a VS Code extension, include configuration defaults in `package.json` with `markdownDescription`.

### Validation & Feedback

- When settings are invalid, log the error and notify users with actionable instructions (“Set `volarJsonYaml.schemas` to an array of objects. See docs URL.”).
- Provide commands or links that open the relevant settings file (VS Code: `workbench.action.openSettingsJson`).

### Profiles / Presets

- Offer easy ways to switch between configurations (commands like “Volar: Use Strict Profile”).
- Document the effect of each profile (diagnostic severity, Take Over Mode, etc.).

## Command Palette & Shortcuts

Provide commands for common tasks:

- “Volar: Restart Language Server”
- “Volar: Clear Schema Cache”
- “Volar: Show Server Logs”
- “Volar: Toggle Take Over Mode”

In Neovim/Sublime, expose equivalents via user commands (`:VolarRestart`, etc.).

## Error Messaging

| Bad | Good |
| --- | --- |
| “Schema fetch failed” | “Schema fetch failed (404). Using cached schema from 2024-05-12. Configure schemas in volarJsonYaml.schemas.” |
| “Config invalid” | “Invalid volarJsonYaml.diagnostics.severity: expected string 'error' | 'warn' | 'info'. Reverted to 'warn'. See docs/…” |

Guidelines:

- Include cause, fallback action, and next steps.
- Link to docs or open configuration automatically when possible.

## Editor Integration Details

### VS Code

- Status bar entry (`window.createStatusBarItem`) with commands.
- Register commands for restart/refresh in `package.json`.
- Respect VS Code’s log level (use `connection.console` so logs appear in “Output ▸ Volar”).

### Neovim

- Provide Lua callbacks to show server status, toggle settings, or display logs.
- Write to a log file (`~/.cache/volar/log.txt`) for easy sharing.

### CLI

- Print progress messages (e.g., “Analyzing 120 files…”) with a spinner.
- Exit with non-zero status when diagnostics contain errors; print summary at the end.

## Documentation & Support

- Maintain a “Known Issues” section (Take Over Mode pitfalls, incompatible extensions).
- Provide reproduction steps for common fixes (clearing Vite cache, installing TS 5.x).
- Encourage users to attach logs + configuration when filing issues; document how to retrieve them.

## UX Checklist

- [ ] Progress indicators for long tasks.
- [ ] Status bar/command to show server status.
- [ ] Clear, actionable notifications for errors/warnings.
- [ ] Settings documented with defaults and examples.
- [ ] Commands for restart, cache clearing, log viewing.
- [ ] Error messages include cause + next steps.
- [ ] Logs accessible via editor output or file.
- [ ] CLI/Neovim equivalents for key UX features.

Thoughtful UX turns a powerful language server into a delightful developer experience. Communicate clearly, surface actionable options, and give users control over how Volar behaves within their editors.