volar-docs/docs/README.md

VolarJS Docs Index & Table of Contents

Use this index to jump to any guide. Each entry lists key sections so you can dive straight into the content you need.

Core Guides

1. Getting Started – mental model, package overview, installation, bootstrapping, integration paths, troubleshooting.
2. Building a JSON/YAML LSP – architecture, setup steps, performance/cancellation, diagnostics/quick fixes, packaging.
3. Plugin Authoring – language plugins, language-service plugins, TypeScript bridge, registration, best practices.
4. Source Map & Code Gen – @volar/source-map and @volar/code-gen APIs, examples, debugging tips.
5. Configuration & Projects – Take Over Mode, monorepos, multi-root workspaces, settings synchronization.
6. Performance & Debugging – profiling, throttling, hotspots, telemetry hooks, troubleshooting scenarios.
7. Testing & CI – unit/integration testing, VS Code/Neovim harnesses, snapshot strategies, CI workflows.
8. Telemetry & Observability – logging, telemetry events, work-done progress, health endpoints.
9. Workspace Diagnostics – protocol primer, result IDs, incremental updates, partial results.
10. Error Handling & Resilience – schema fallbacks, configuration validation, restart strategies.
11. UX Best Practices – progress indicators, notifications, settings UX, editor-specific guidance.
12. LSP Benchmarking – metrics, tooling (lsp-bench, custom harnesses), reporting, CI automation.
13. Troubleshooting & FAQ – quick fixes for duplicate diagnostics, schema fetch failures, logging.
14. Release & Upgrade Guide – version matrix, upgrade checklist, CI matrices.
15. Vetur Migration – step-by-step instructions for moving from Vetur to Volar.
16. Custom Diagnostics – recipe for building project-specific diagnostic plugins.
17. Monaco Playground – integrating Volar with browser playgrounds via @volar/monaco.
18. Volar Kit, Editor & Monaco – bootstrap servers with @volar/kit, embed language services in custom editors, and integrate with Monaco.
19. TypeScript Plugin Deep Dive – @volar/vue-typescript, compiler options, macros, diagnostics control.
20. Volar Service Catalog – official/community volar-service-* plugins and configuration patterns.
21. CLI Integration – building vue-tsc-style headless tooling, workspace diagnostics in CI.
22. Alternative Editor Integration – guidance for JetBrains, Sublime, Neovim, Emacs, custom editors, VS Code Web.
23. Cross-Language Recipes – adapting Volar’s architecture to Astro, Svelte, Marko, Tailwind-heavy setups, etc.
24. Package API Reference – quick lookup for @volar/editor, @volar/language-service, @volar/typescript, etc.
25. Response Formatting & Content – best practices for diagnostics, hovers, completions, and code actions.

Example Catalogue

• Live Examples – curated list of editor extensions, online IDEs, CLI tooling, and community plugins powered by VolarJS.

Examples

• examples/json-yaml-lsp – runnable project combining Volar with JSON/YAML services, showcasing diagnostics, quick fixes, $ref definitions, workspace diagnostics, and configuration reloads.

Suggested Reading Order

1. Start with Getting Started to grasp the core packages.
2. Follow with Plugin Authoring and Source Map & Code Gen if you plan to extend Volar.
3. Consult Configuration & Projects before rolling out to monorepos or multi-root workspaces.
4. Use Performance, Testing, Telemetry, and Error Handling guides to harden your server.
5. Refer to UX Best Practices and Benchmarking when polishing the user experience and ensuring regressions don’t slip in.

Cross-Links

Every guide links back to this index via its navigation header. If you create new docs, add them here so the ecosystem stays discoverable.