volar-docs/docs/ux-best-practices.md

UX Best Practices for Volar-based Language Servers

Docs Index • Repo README • Telemetry • Error Handling

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

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'

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.