Building a VS Code Extension with Xtext and the Language Server Protocol

In the upcoming Version 2.11, Xtext will support the Language Server Protocol defined by Visual Studio Code. This is a very important step, as the protocol is generic and is going to be supported by other editors such as Eclipse or Che as well. In this post I want to give the early adopters among us a head start and explain how to use this exciting new feature.

Try the Example Language

Installing a language extension in VS Code is easy: open the “Extensions” view on the left sidebar and search for “typefox”. Install and activate the “mydsl” language, create a new file with that extension (e.g. test.mydsl), and explore the editor support for this simple DSL. Here’s an example snippet:

The source of this example is available on GitHub. It has two main components: an Xtext example language consisting of a base project (io.typefox.vscode) and an IDE support project (io.typefox.vscode.ide), and a VS Code extension project (vscode-extension). You can compile and run the example with the following steps:

  1. Run ./gradlew installServer
  2. Open the vscode-extension project with VS Code.
  3. Run npm install in the integrated terminal (View → Integrated Terminal).
  4. Press F5 to start a second instance of Code.
  5. Test the language as described above.

Create Your Own Language Extension

In case you haven’t done that yet, start by creating an Xtext project and choosing Gradle as build system. Make sure your Xtext version in the gradle build files is bumped to 2.11-SNAPSHOT. In order to create a VS Code extension for your language you need to build an executable application from it. I recommend the Gradle application plugin for this, which gives you a bundle with all required libraries and a startup script. Just add the following lines to the build.gradle of the ide project of your language:

The command gradle installDist generates the executable in the subfolder build/install.

As a next step, create a VS Code extension following the documentation. The official example uses a Node.js module to implement the server. You can change that to start your language server application by using the following code in extension.ts to create the server options:

If you have set up your VS Code project properly, you should now be able to start a second Code instance that includes your extension by pressing F5. Open a folder in that new instance and create a file according to the file extension of your language. Now language support should be active, and the debug console of the host instance of Code should show a message like “Loading development extension at …” – You’re done!

How Xtext Integrates with VSCode

In VS Code a language server is a process that is started and used by an extension, i.e. a plug-in for VS Code. The process application can be implemented in any programming language, and VSCode speaks to it through an input and an output stream (i.e. standard in/out or a socket).

Starting and Initializing

After launching the process, VS Code initializes the language server by sending a message. This message includes a path to the root directory the editor is looking at (unless the file is opened without a root directory). In Xtext we take that directory and do a quick build that includes indexing. In order to tell what kind of project structure we are looking at, the Xtext language server will be capable of using different project description providers. One for instance could be able to ask Gradle for the modules and dependencies, another could simply read ‘.project’ and ‘.classpath’ files. At the time of writing this we only have a dump; treat it as one project without implementation of dependencies. However, this will change in the coming weeks.

During the first build, Xtext might already find problems in your source code. In that case the language server will send notifications to the editor reporting those diagnostics.

Many Languages per Server

Usually a language server is responsible for one language. However, in order to allow cross-language linking and transitive dependency analyses, the Xtext language server can host as many langauges as you want. For VS Code it will look like one language with many different file extensions. The language server is a common reusable component that you don’t need to configure besides the project description provider mentioned above. The participating languages are loaded through a Java ServiceLoader for the type ISetup. The necessary entry under META-INF is generated for you if you use the latest nightly build.


The Xtext 2.11 release is planned for October 2016. This version will already allow you to create language support extensions for VS Code, but you can expect more interesting integrations in the future, e.g. the web IDE Che.

The current language server implementation of Xtext builds on the ls-api library, which I described in a previous post. This library is going to be moved to LSP4J, a new project proposed under the Eclipse umbrella.

By | 2016-11-30T08:34:08+00:00 July 27th, 2016|DSLs, Eclipse, Language Server, Xtext|17 Comments

About the Author:

Miro is a software engineer and consultant at TypeFox and a committer for Xtext, ELK, and LSP4J. He started to get involved into open source development while researching graph layout algorithms and their application to graphical modeling at the University of Kiel. Miro's contributions to KIELER, an academic project on modeling pragmatics and semantics, have been the foundation of his doctoral thesis and are now part of the ELK project.


  1. Carl July 28, 2016 at 08:42 - Reply

    Hi Miro,
    thanks for posting this. Tried to install the mydsl extension following your steps.
    After the installation was successful, I restarted VS Code and created a new file with the extension “.mydsl”. I’m not aware if there is anything else to do in order to “activate” the extension (if there is, it would be nice to either explain that or put a link in your post). I don’t get a lot of IDE support at the moment, frankly.
    Some keywords are highlighted, that’s pretty much it, which let me to believe it is not working for me. I’m on VS Code 1.3.1.

    • Miro Spönemann July 28, 2016 at 08:50 - Reply

      VS Code displays an “Enable” button after an extension has been installed from the extensions view. If the language support is still missing after that, please create an issue here and include information about the system you’re using:

      • Carl July 28, 2016 at 10:31 - Reply

        Well, the “enable” button seems to do pretty much the same as restarting VS Code. But I cannot test it anymore. I uninstalled the extension and trying to re-installing fails (gave it 15 minutes now after clicking the “install” button, nothing is happening though). I don’t think I have enough data points to file a issue yet.

  2. […] this as I am, you could try it out today already (there is still work ahead of us). Miro published a tutorial about it a couple of days […]

  3. […] Eine Anleitung, wie man Xtext mit dem Language Server Protocol verwenden kann, gibt es auf dem Blog von TypeFox. […]

  4. Jose Badeau October 5, 2016 at 21:24 - Reply

    JHipster is currently working on a vscode plugin for their DSL based on this post:

  5. […] a previous post I described the basic steps to combine your DSL with a Language Server Protocol client. The Xtext […]

  6. Chetan Laddha December 6, 2016 at 14:43 - Reply

    Do we have any steps for Building a Eclipse Che Code Extension with Xtext and the Language Server Protocol ?

  7. […] Alle Xtext-2.11-Plug-ins benötigen Java 8, empfohlen sind Eclipse-Versionen ab Eclipse Luna. Eine Anleitung, wie man Xtext mit dem Language Server Protocol verwenden kann, gibt es auf dem Blog von TypeFox. […]

  8. Chetan Laddha February 17, 2017 at 08:43 - Reply

    Thanks, Miro.

    Who takes care of syntax highlighting? When I am creating my own custom dsl, I am not able to see any my **.tmLanguage file. Does Xtext language server generates this file or you created manually ?

    • Miro Spönemann February 17, 2017 at 08:54 - Reply

      Currently a syntax highlighting generator for VS Code is not provided by Xtext. I’m not sure whether it will be provided in the future. But if you need it, it’s not hard to implement you own generator fragment for that: see how the other fragments are realized, e.g. the WebIntegrationFragment.

      • Chetan Laddha March 9, 2017 at 15:13 - Reply

        How this WebIntegrationFragment generated fragment will be helpful in case of Symbol Highlighting? How I can use them in an integration of language server? Could you please describe in more detail or any link to any document/blog will be very helpful.

        • Miro Spönemann March 22, 2017 at 09:08 - Reply

          Implementing a generator fragment was just an idea, but of course that’s a lot more complicated than just implementing a syntax highlighter directly. I think currently there is no documentation on implementing generator fragments. So the easiest way would be to write a colorizer according to the VS Code documentation.

  9. Chetan Laddha March 3, 2017 at 11:38 - Reply

    As per my understanding, In your context, it creates the package everything and xtext-server-example folder get’s deployed.
    How I can debug my xtext language server (xtext ide module) in visual code?

    • Miro Spönemann March 6, 2017 at 09:12 - Reply

      You can add command line arguments where you create the Java process in the VS Code extension. Use arguments such as

      and connect to port 8000 with a remote debug configuration in Eclipse.

Leave A Comment