Editor support

The mistakes xoong check reports can show up while you type. There are two ways to get that, and they work together: HTML custom data, which gives completion and hover in VS Code with nothing to install, and a language server, xoong-lsp, which adds the checks themselves, quick fixes and completion in any editor that speaks LSP.

Which one

HTML custom data in VS Code

xoong sync writes .xoong/xoong.html-data.json next to operations.json, and so does xoong new. It is the format that VS Code's HTML language service reads. Point the editor at it once, in .vscode/settings.json:

{
  "html.customData": ["./.xoong/xoong.html-data.json"]
}

{
  "version": 1.1,
  "globalAttributes": [
    {
      "name": "xo-click",
      "description": "Call an operation when clicked: \"METHOD /path/{param}\" or an operationId. Params come from the current item, then the view's p-* params.",
      "valueSet": "xo-mutations"
    }
  ],
  "valueSets": [
    {
      "name": "xo-mutations",
      "values": [
        {
          "name": "DELETE /api/people/{id}"
        },
        {
          "name": "POST /api/people"
        },
        {
          "name": "PUT /api/people/{id}"
        },
        {
          "name": "createPerson"
        },
        {
          "name": "deletePerson"
        },
        {
          "name": "updatePerson"
        }
      ]
    }
  ]
}

You then get, in HTML files:

• completion and hover documentation for every xo-* element and attribute, with the attributes of the element you are in;
• the real operation names for xo-click, xo-submit, <xo-view get> and <xo-form op>: mutations for the first two and for op, reads for get;
• p-<name> attributes for the path parameters of your API on a view;
• the values of attributes that take a fixed set (xo-confirm-kind, <xo-dialog size>, the sizes and statuses of the controls).

The file is made again by every sync, so it follows the API. It only offers; it does not check, and it does not fix.

The language server

xoong-lsp is a language server for the Language Server Protocol, over standard input and output. It finds .xoong/operations.json from the workspace folder upward and reads it again when it changes; saving a file checks it again, which also picks up a fresh xoong sync. It needs no options.

npm install --save-dev @xoong/lsp@next
npx xoong sync openapi.json
npx xoong-lsp                # started by your editor, not by hand

Any editor with a language-server client can run it: the command is npx xoong-lsp, the files are HTML, JavaScript and TypeScript, and the root is the folder with .xoong/. In Neovim:

vim.api.nvim_create_autocmd('FileType', {
  pattern = { 'html', 'javascript', 'typescript' },
  callback = function(args)
    vim.lsp.start({
      name = 'xoong',
      cmd = { 'npx', 'xoong-lsp' },
      root_dir = vim.fs.root(args.buf, '.xoong'),
    })
  end,
})

VS Code has no setting that starts an arbitrary language server, so there the custom data above is what you use; an extension that wraps the server is planned.

What it gives you

The packages' tests cover each of these. A test also fails when an element or attribute is added to the syntax lists and the server cannot complete or explain it.

Limits

• There is no VS Code extension yet, and no commands, status bar or snippets. Lint presets and SARIF output are planned.
• Completion of {field} paths does not know the scope yet, hover does not show the types of an operation, and there is no go to definition.
• The editor sends the whole text of a file on every change (full document sync), which is fine for screens and not meant for huge files.
• It checks what the editor sends it. Tell your editor which file types to use it for.

See also: Command line · MCP server · Error codes · How it is built