This article is part of a series to help newcomers to get started with Eclipse Theia development by setting up a local docker-based development environment for Theia.
After setting up a Theia Development environment (either with Docker Dev Environments or VS Code Remote Containers), the next step is to actually write some code.
This article provides a good description of the process of creating a first extension with the help of a yeoman code generator. This code generator actually takes care of creating both the extension code and a custom theia product. So we don’t even have to use the package.json from my previous articles. But since we have already a development container set up, we will just reuse the existing environment here.
So let’s just ignore the existing files, open a Terminal in our Docker workspace and create a new folder hello-world. Then we change into the new folder with and invoke the code generator:
$ mkdir hello-world
$ cd hello-world
$ yo theia-extension
In the dialog that follows, we select the Hello World extension and just accept the proposed name.
Now, first the code generator and then yarn will do their thing again to get the new Theia instance set up and resolved, and in the end, we can start theia by executing yarn start:browser.
In the Theia application that is running now, note that we have a new menu item Say Hello in the Edit Menu. When selecting this item, a message in the lower right says Hello World.
Let’s try to modify the message. But first, in order to have our our code changes be picked up, we need to tell the TypeScript compiler to watch the code. Watching means, that any change to the code in a .ts file is directly picked up and compiled to JavaScript. For developers being used to the Eclipse IDE, this is the equivalent of activating Project > Build Automatically. Open up a New Terminal, and–as we will only make changes to the hello-world extension–change to the folder of our hello-world extension and execute yarn watch from there. Restricting the watch to the extension folder will save resources, as only the files in that folder need to be watched.
Now find and open the hello-world-contribution.ts file in the VS Code editor and change the message in line 19 to Hello changed world!. Save the file, and you will briefly see the console blink as it picks up the changes and reports "Found 0 errors".
Finally, we need to reload the Theia page in the browser if it still open. The reason is that the code that produces the message was compiled from TypeScript to JavaScript, but as it is frontend code, it has actually been loaded and is executed in our web browser.
Executing and changing code is one thing, but sooner or later, we will want to inspect what is going on at runtime by using a debugger. So, let us create a breakpoint at the line in which we have changed the message and try to hit it.
Note that, as stated above, this line is part of the frontend code, so we need to attach a debugger to the frontend, which means the browser. So, we could use the builtin development tooling that is part of all web browsers, nowadays. But the browser does not know about TypeScript and the TypeScript compiler; it only knows about JavaScript which it loads and executes. Consequently, we would not be able to hit the breakpoint set in VS Code. Instead, we would need to find out which line in JavaScript relates to the line in TypeScript, and set a breakpoint in this line in the browser’s development tools. In practice this seems to be cumbersome and error-prone.
Luckily, VS Code also has a frontend debugging feature that is able to attach to a debug server built into Google Chrome or Microsoft Edge browsers. The setup is quite simple: Switch to the Run and Debug view in the Activity Bar and click the Create launch.json File link. Then select the Chrome environment and adapt the file to contain
{
"version": "0.2.0",
"configurations": [
{
"type": "pwa-chrome",
"request": "launch",
"name": "Launch Chrome against localhost",
"url": "http://localhost:3000",
"webRoot": "${workspaceFolder}/hello-world/hello-world"
}
]
}
Note that the url property needs to set so it points to the port at localhost on which Theia is running. The webRoot property needs to point to the actual path in the workspace where the code of the extension is located. This is used to connect the breakpoint position to the browser’s debug server. If this property is set to a wrong location, you will see it marked as Unbound while the debugger is run.
Now, all we have to do is make sure that Theia (i.e., yarn start:browser) is still running and start the Launch Chrome against localhost Debug Configuration. Now click on the „Say Hello“ menu item again, and the execution should suspend and the debugger should show the stack, variables, etc. and we can use the debugger to step through the code as it is executed.
That’s it for today. As the hello-world extension does not include any backend code, we will postpone backend debugging to a future article.
This article is part of a series to help newcomers to get started with Eclipse Theia development by setting up a local docker-based development environment for Theia.
After having written the previous article Getting started with Eclipse Theia (1): Starting Theia Development in a Docker Dev Environment, I have tried the same setup on a different machine which does not have a Docker Desktop installation, but which uses docker-machine to manage its containers in a boot2docker VM.
My goal was to achieve a similarly easy startup on this machine (and also on Linux machines for which Docker Desktop is not available). By digging a bit deeper into the inner workings of the Docker Dev Environments feature, I have learned that most of the functionality is also available in VS Code directly via the Remote Containers Extension.
Similar to the Docker Dev Environments feature, you can add a folder .devcontainer to a repository containing a file called devcontainer.json. Then, anyone can directly clone this repository and start working on it inside a docker container with VS Code. This is how my devcontainer.json file looks like:
{
"name": "theia-dev",
"context": "../docker-container",
"dockerFile": "../docker-container/Dockerfile",
"forwardPorts": [3000],
"postCreateCommand": "yarn && yarn theia build",
"remoteUser": "node"
}The Dockerfile referenced here is the same we have used for the Docker Dev Environments in the last article.
To get started, after installing the Remote Containers Extension in VS Code, follow these steps:
github.com/xpomul/theia-boilerplate.git) and follow the navigation to select your GitHub repositoryyarn and yarn theia build commands will be executed automatically (as specified in the devcontainer.json).yarn theia start --plugins=local-dir:plugins and your Eclipse Theia instance will come up at http://localhost:3000 Again, from here, you can follow the usual Theia tutorials and start experimenting.
Have fun!
This article is part of a series to help newcomers to get started with Eclipse Theia development by setting up a local docker-based development environment for Theia.
So here it is. After over 10 years of Eclipse development, I wanted to get my hands dirty on something entirely new. I have followed the developments of Orion, Che, and Theia for a long time, but only from a distance; and I just didn’t have the time to actually try out, let alone to get involved with, these projects.
I have used Gitpod a few times, but merely to have a quick look into a GitHub repository when I didn’t have a local development environment and didn’t want to get one up and running.
Yet, I have noticed an increasing interest from my customers in web-based environments and so, I wanted to finally play around with Eclipse Theia.
But how? I have found this article which provides several options to run Eclipse Theia in different ways, but none of those options really hit the spot for me. I wanted to run a Theia instance in my browser, so Theia Blueprint was not an option. I wanted to be able to work offline, so using Gitpod was not possible. And I didn’t want to install nodejs on my machine. But still the goal was to get a basic Theia product up and running that should be ready to start hacking and customizing it, and then to jump in and create my first Theia extension.
I had started, and aborted again, several attempts to create a Docker container in which I could do that. But so far, I had not managed to create a smooth environment.
Domain specific languages are a great tool when we want to give our users control over complex aspects in our applications; and in most cases, experienced uses can learn syntax and semantics of a well-designed DSL quickly. But on the other hand, there are also inexperienced users, who usually struggle with DSLs and do not want to deal with textual input. Instead, they are used to graphical user interfaces which help them to grasp the structure of information and to enter new data.
Last week, I had a project, in which I needed to provide both groups of users with a suitable user interface. In other words, I needed to create an editor, which provides both an Xtext source editor for my DSL, and a GUI editor for the model behind the DSL.
I started to search the Internet for some hints on how to do this but I did not find a complete example. Basically, to combine multiple editors into a single one, we have to subclass and implement an org.eclipse.ui.part.MultiPageEditorPart. But I did not find more than hints about how to share the model between an Xtext editor and another editor. So, I started experimenting and after some time I was successful, and I wanted to let you participate in my results. Maybe this helps someone who is looking for an example as well.
For the rest of this post, I will use the state machine example that comes with the Xtext distribution as a starting point. To demonstrate the solution I will add a GUI editor for events to the generated Xtext editor. For brevity, I will only show the relevant parts. The full modified example source code is available on GitHub.