Recommended resources to reference before we release the documentation

[johnsoncodehk]

I get many requests for documentation, but since the API design is still unstable, it doesn't make much sense to write documentation at the moment, as it will most likely be outdated very quickly.

Instead I suggest you refer to the implementation examples in the community.

This is a very simplified diagram of how the modules work together in the current version (v1.8).

Common Misconceptions

• The current version number is 1.x, which does not mean it is stable, because the version number actually inherits from vuejs/language-tools. The real first stable release will be 2.0.

• Volar.js is described as a framework for implementing embedded language, but in actuality Volar.js implementation is both conventional regular language and embedded language, and it works with any language other than meta-frameworks. Even if you don't need embedded language support, you can still take advantage of Volar.js' infrastructure of LSP, Monaco, CLI integration, and more.

Getting Started

I suggest you start from https://github.com/volarjs/starter, try to compile, run it and look at the code, you should be able to understand the concept of Volar.js, especially how to create VirtualFile and handle mapping. This is the basis for all integrations.

LSP server + VSCode extension

Integration reference:

• Getting Started☝️
• Astro: https://github.com/withastro/language-tools
• Vue: https://github.com/vuejs/language-tools
• TSConfig Helper: https://github.com/johnsoncodehk/tsconfig-helper

LSP server for Web (github.dev, vscode.dev)

• TypeScript IntelliSense for Web: https://github.com/volarjs/vscode-typescript-web

LSP clients other than VSCode

Integration reference:

• https://github.com/vuejs/language-tools#community-integration

@volar/typescript for TS plugin (tsserver plugin)

For an introduction to TS plugin, please refer to the official documentation: https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin

Integration reference:

• typescript-vue-plugin: https://github.com/vuejs/language-tools/blob/master/packages/vue-typescript/src/index.ts
• @astrojs/ts-plugin: https://github.com/withastro/language-tools/blob/main/packages/ts-plugin/src/index.ts
• typescript-plugin-asset: https://github.com/mizdra/typescript-plugin-asset

@volar/typescript for tsc

Integration reference:

• vue-tsc: https://github.com/vuejs/language-tools/tree/master/packages/vue-tsc

Monaco

Integration reference:

• @vue/repl: https://github.com/vuejs/repl/blob/main/src/monaco/vue.worker.ts
• monaco-volar: https://github.com/Kingwl/monaco-volar/blob/main/src/vue.worker.ts
• tsplay.dev: [WIP] volar support for the LSP gillchristian/tsplay.dev#116

Services API

Integration reference:

• Getting Started☝️: https://github.com/volarjs/starter/blob/2ffa7678dc8200c120970f3843f86e1b26cbbe05/packages/language-server/src/index.ts#L20-L43
• volar-service-*: https://github.com/volarjs/services

Scripts API (@volar/kit)

Introduction: https://blog.vuejs.org/posts/volar-a-new-beginning

Integration reference:

• astro-check: https://github.com/withastro/language-tools/blob/main/packages/language-server/src/check.ts
• refactor: Migrate format tests to Scripts API vuejs/language-tools#3133

[johnsoncodehk]

Additional: I also highly recommend using Volar.js Labs for debugging.

Implement reference:

• https://github.com/vuejs/language-tools/blob/a73e249f6b5638e7029c0c929eb704e2230a5af3/packages/vscode-vue/src/nodeClientMain.ts#L111-L118
• https://github.com/withastro/language-tools/blob/d71c081ae89ad3ca481996234bd04c0bf7148a16/packages/vscode/src/client.ts#L85-L91