Examples of Language Service Plugin

[johnsoncodehk]

Relate issues: #672, #734

Implementation version: 0.33.0

NOTE: This feature may change before 1.0

Checkout https://github.com/johnsoncodehk/volar/blob/master/packages/vue-language-service-types/src/index.ts for all available apis.

Disable built-in sass formatter

volar.config.js (It should be in same folder with tsconfig.json):

module.exports = {
    plugins: [
        require('./volarPlugins/disable-sass-format').default(),
    ],
};

volarPlugins/disable-sass-format.ts (You need to build it to js by tsc volarPlugins/disable-sass-format.ts --skipLibCheck):

import type { EmbeddedLanguageServicePlugin } from '@volar/vue-language-service-types';

export default function (): EmbeddedLanguageServicePlugin {

    return {

        format(document, range, options) {

            if (document.languageId === 'sass')
                return []; // return empty array instead of undefined to avoid progress to next plugin
        },
    }
}

Prettier

You could also check this example in https://github.com/johnsoncodehk/volar-starter.

package.json:

{
  "devDependencies": {
    "prettier": "latest",
    "@volar/vue-language-service-types": "latest"
  },
  "scripts": {
    "postinstall": "tsc volarPlugins/prettier.ts --skipLibCheck"
}

volar.config.js:

module.exports = {
    plugins: [
        require('./volarPlugins/prettier-html').default(['html', 'css', 'scss', 'less']),
    ],
};

volarPlugins/prettier.ts:

import type { EmbeddedLanguageServicePlugin } from '@volar/vue-language-service-types';
import * as prettier from 'prettier';

export default function (languages: string[]): EmbeddedLanguageServicePlugin {

    return {

        format(document, range, options) {

            if (!languages.includes(document.languageId))
                return;

            const formattedText = prettier.format(document.getText(), {
                tabWidth: options.tabSize,
                useTabs: !options.insertSpaces,
                parser: document.languageId,
            });

            if (formattedText === document.getText())
                return [];

            return [{
                range: {
                    start: document.positionAt(0),
                    end: document.positionAt(document.getText().length),
                },
                newText: formattedText,
            }];
        },
    }
}

prettyhtml

package.json:

{
  "devDependencies": {
    "@starptech/prettyhtml": "latest",
    "@volar/vue-language-service-types": "latest"
  },
  "scripts": {
    "postinstall": "tsc volarPlugins/prettyhtml.ts --skipLibCheck"
}

volar.config.js:

module.exports = {
    plugins: [
        require('./volarPlugins/prettyhtml').default(100),
    ],
};

volarPlugins/prettyhtml.ts:

import * as prettyhtml from '@starptech/prettyhtml';
import { EmbeddedLanguageServicePlugin } from '@volar/vue-language-service-types';

export default function (printWidth: number): EmbeddedLanguageServicePlugin {

	return {

		async format(document, range, options) {

			if (document.languageId !== 'html')
				return;

			const newHtml = prettyhtml(document.getText(), {
				tabWidth: options.tabSize,
				useTabs: !options.insertSpaces,
				printWidth: printWidth,
			}).contents;

			if (newHtml === document.getText())
				return [];

			return [{
				range: {
					start: document.positionAt(0),
					end: document.positionAt(document.getText().length),
				},
				newText: newHtml,
			}];
		},
	}
}

---

If you have other plugin implementations, you can also share them here.

[mariusa]

Great! How can one switch from prettyhtml to build-in vscode formatting?

In Extension settings, I don't see any setting to choose a formatter.

Marketplace Info
Last updated
14/03/2022, 20:34:12

[johnsoncodehk]

See Use Prettier instead of built-in HTML formatter section, you need to change prettier to vscode-html-languageservice.

[mariusa]

Thanks! Hoping this thread will lead to updating the initial post with a complete working howto.
I was expecting a Setting allowing to choose which formatter, similar to vscode settings.

I've created volar.config.js at the top my of project, same level as vite.config.js

Content:

module.exports = {
    plugins: [
        require('vscode-html-languageservice'),
    ],
}

(could this be written with ESM syntax, same as vite.config.js?)

Also in project, as it doesn't work with a global install:
npm install --save vscode-html-languageservice
(I didn't think this was necessary, since it's included in vscode?)

What else is needed? It still uses prettyhtml (I'm checking with #970)

[johnsoncodehk]

Actually I'm considering change built-in formatter to vscode-html-languageservice and migrating prettyhtml to an external plugin, will let you know when I finally decide.

[johnsoncodehk]

@mariusa Please track #1078.

[mariusa]

Thank you!

[douglasg14b]

@johnsoncodehk Where could we find the implementation of this API to supplement the lack of jsDocs? Even better, examples of each of the available functions, or links to good examples of where they are used?

[johnsoncodehk]

What do you mean the lack of jsDocs? If there are a issue please share.

For more plugins example, you could see https://github.com/johnsoncodehk/volar/tree/master/packages/vue-language-service/src/commonPlugins.

[douglasg14b]

Sorry if I was unclear, in the link in the OP. The API has a bu ch of functions, but not much explanation that describes them. The names give hints, but that's pretty bare bones.

I'm not complaining that hard here, but it does make it harder when I want to try and make a plugin to expand capabilities (Adding Veutr JSON definitions support), as I have zero idea what I'm doing or looking at.

I'll look through those, thanks!

[johnsoncodehk]

You can start with the following code, and you need to implement loadVeturComponentData yourself.

import type { EmbeddedLanguageServicePlugin } from '@volar/vue-language-service-types';
import * as html from 'vscode-html-languageservice';

export default function (): EmbeddedLanguageServicePlugin {

	const htmlDocuments = new WeakMap<TextDocument, html.HTMLDocument>();
	const htmlLs = html.getLanguageService();
	const veturData = loadVeturComponentData(); // you have to implement this
	htmlLs.setDataProviders(
		false, // volar built-in html plugin already have it
		veturData,
	);

	return {

		complete: {

			// https://github.com/microsoft/vscode/blob/09850876e652688fb142e2e19fd00fd38c0bc4ba/extensions/html-language-features/server/src/htmlServer.ts#L183
			triggerCharacters: ['.', ':', '<', '"', '=', '/'],

			isAdditional: true,

			// auto-complete html tag, attr from vetur component data
			on(document, position, context) {
				return worker(document, htmlDocument => {
					return htmlLs.doComplete(document, position, htmlDocument);
				});
			},
		},

		// show hover info for html tag, attr from vetur component data
		doHover(document, position) {
			return worker(document, htmlDocument => {
				return htmlLs.doHover(document, position, htmlDocument);
			});
		},
	}


	function worker<T>(document: TextDocument, callback: (htmlDocument: html.HTMLDocument) => T) {

		const htmlDocument = getHtmlDocument(document);
		if (!htmlDocument)
			return;

		return callback(htmlDocument);
	}

	function getHtmlDocument(document: TextDocument) {

		if (document.languageId !== 'html')
			return;

		let htmlDocument = htmlDocuments.get(document);

		if (!htmlDocument) {
			htmlDocument = htmlLs.parseHTMLDocument(document);
			htmlDocuments.set(document, htmlDocument);
		}

		return htmlDocument;
	}
}

[yaegassy]

Hi, @johnsoncodehk

[NG]:

import type { EmbeddedLanguagePlugin } from '@volar/vue-language-service-types';

[OK]:

import type { EmbeddedLanguageServicePlugin } from '@volar/vue-language-service-types';

[johnsoncodehk]

Forgot to update example code, thanks!

[patarapolw]

A working /volarPlugins/prettier.js for prettier alone (no eslint). I don't know how the OP can just require a TypeScript just like that, but I can't...

const { format, resolveConfigFile, resolveConfig } = require('prettier')
const { randomUUID } = require('crypto')

/**
 *
 * @param {string[]} languages
 * @returns {import('@volar/vue-language-service-types').EmbeddedLanguageServicePlugin}
 */
module.exports = function volarPrettierPlugin(languages) {
  const prettierConfig = resolveConfig.sync(resolveConfigFile.sync())

  const makeUUID = () => `{{'${randomUUID()}'}}`
  const uuidRegex = (() => {
    const c = '[0-9a-f]'
    return new RegExp(makeUUID().replace(new RegExp(c, 'g'), c), 'g')
  })()

  /** @type {import('@volar/vue-language-service-types').EmbeddedLanguageServicePlugin} */
  return {
    format(document, range, options) {
      // I don't if what is return matters or not. It is `NullableResult<TextEdit[]>` after all.
      if (!languages.includes(document.languageId)) return []

      const originalText = document.getText()

      let preFormattedText = originalText
      const isHTML = document.languageId === 'html'

      // Prettier breaks {{'...long line...'}} in <template> tags, without a good fix.
      // {{'...shorter line...'}} {{'...shorter line...'}} doesn't appear to work.
      // The only real another fix is <span> {{'...shorter line...'}} </span>
      const noBreak = new Map()
      if (isHTML) {
        preFormattedText = preFormattedText
          .replace(
            /( *){{ *((['"])[^]+?\3) *}}( *)/g,
            (raw, w1, content, bracket, w2) => {
              const id = makeUUID()
              raw = `{{ ${content} }}`
              noBreak.set(id, raw)
              return w1 + id + w2
            }
          )
          // This one is opinionated, but I just put it here, anyway.
          .replace(/> ?({{.+?}})/g, '> $1')
          .replace(/({{.+?}}) ?</g, '$1 <')
      }

      let formattedText = format(preFormattedText, {
        ...prettierConfig,
        tabWidth: options.tabSize,
        useTabs: !options.insertSpaces,
        filepath: document.uri
      })

      if (isHTML) {
        formattedText = formattedText.replace(uuidRegex, (raw) => {
          return noBreak.get(raw) || raw
        })
      } else {
        formattedText = '\n' + formattedText
      }

      if (formattedText === originalText) return []

      return [
        {
          range: {
            start: document.positionAt(0),
            end: document.positionAt(originalText.length)
          },
          newText: formattedText
        }
      ]
    }
  }
}

/volar.config.js

module.exports = {
  plugins: [
    require('./volarPlugins/prettier')([
      'html',
      'css',
      'scss',
      'less',
      'typescript',
      'javascript'
    ])
  ]
}

This itself also tells a bug... Without if (document.languageId !== 'html') { formattedText = '\n' + formattedText }, both <script> and <style> will collapse.

<script setup lang="ts">import { ref } from 'vue'
...
</script>

...

<style scoped>section {
...
}
</style>

I suspect this is exactly the same issue as #1155, albeit some minor differences (that }</style>).

It appears that a fake filepath is generated at document.uri, and can be used to instruct the prettier. I suspect this (filepath: document.uri) is better than parser: document.languageId, as in the OP. (Also, javascript parser isn't a thing.)

[johnsoncodehk]

I don't know how the OP can just require a TypeScript just like that

I have build it to .js with postinstall.

I don't if what is return matters or not. It is NullableResult<TextEdit[]> after all.

Yes it is matters, you should return undefined instead of [] if this plugin do not progress this document.

I have move this plugin to https://github.com/johnsoncodehk/volar-plugins/tree/master/packages/prettier, since I don't use prettier, can you be a maintainer?

[patarapolw]

I am not exactly sure how to use pnpm-workspace, and interop with Yarn (yarn link?)

I suppose I have to edit /packages/prettier/src/index.ts, then run pnpm build.

Another thought is, whether it is possible to have a tester inside volar-plugins repo?

[johnsoncodehk]

pnpm-workspace is just for reduce node_modules size, we will not link other packages in monorepo side by side.

I don't add tests for @volar-plugins/prettier-html / @volar-plugins/prettier, but you can feel free to do.

Just out of curiosity, seems you're using prettier for all embedded languages, why you are not just use prettier extension?

[patarapolw]

why you are not just use prettier extension?

Not that you mentioned it, I can indeed format with prettier directly.

Prettier itself also seems to know that <template> is actually Vue, and inside {{}} is JavaScript. document.uri / document.languageId got it misleading.

Nonetheless, for now, I can write preprocesser / post-processer this way.

There are things that I dislike about prettier for HTML, like this one.

	<p>
		<a href="https://vitejs.dev/guide/features.html" target="_blank"
			>Vite Docs</a
		>
		|
		<a href="https://v3.vuejs.org/" target="_blank">Vue 3 Docs</a>
	</p>

PrettyHtml got it better.

	<p>
		<a href="https://vitejs.dev/guide/features.html" target="_blank">Vite Docs</a> |
		<a href="https://v3.vuejs.org/" target="_blank">Vue 3 Docs</a>
	</p>

Still, I would use Prettier for TS / JS / TSX / JSX formatting.

Also, I am not sure about integrating eslint, but I use only prettier to reduce complexity...