How to setup a project with Theia integration?

[rsoika]

Hi,
I can't figure out how to setup my project to work with theia integration.

I have the following project structure:

myproject/
├── glsp-client
│   ├── bpmn-glsp/
│   ├── bpmn-standalone/
│   └── ..............
├── glsp-server
│   ├── plugin.xml
│   ├── pom.xml
│   └── ..............
├── glsp-theia
│   ├── configs
│   ├── examples
│   ├── packages
│   └── ..............
├── pom.xml

The server works fine, and also I can build my client component with yarn install. Also I can run the bpmn-standalone/app/diagram.html from my browser, so that I can see server and client is working. The code is more or less from the glsp-workflow-example.

The problem now is the glsp-theia integration. I took the glsp-theia-integration project as a template. But this template refers again to the official dependency of the glsp-workflow example

  "dependencies": {
    "@eclipse-glsp-examples/workflow-glsp": "next",
    "@eclipse-glsp/theia-integration": "0.9.0"
  },

Of course I can not use this in my own project. But changing this dependency to my own project also don't work

  "dependencies": {
    "@imixs-bpmn/bpmn-glsp": "0.0.1", 
    "@eclipse-glsp/theia-integration": "0.9.0"
  },

because yarn complains that the dependency @imixs-bpmn/bpmn-glsp": "0.0.1" can not be found.

First I tried with linking packages which ended up in a total mess.

after some hours I tried to add the following dependency into the parent package.json

"dependencies": {
"parent": "file:../imixs-bpmn.glsp-client/"
}

But this leads still to warnings like this one:

browser-app: WARNING in ../../node_modules/inversify/lib/syntax/binding_when_syntax.js
browser-app: Module Warning (from ../../node_modules/source-map-loader/dist/cjs.js):
browser-app: Failed to parse source map from '/home/rsoika/git/imixs-bpmn.glsp/imixs-bpmn.glsp-theia/node_modules/inversify/src/syntax/binding_when_syntax.ts' file: Error: ENOENT: no such file or directory, open '/home/rsoika/git/imixs-bpmn.glsp/imixs-bpmn.glsp-theia/node_modules/inversify/src/syntax/binding_when_syntax.ts'

I know that this is a yarn problem, but as a Jakarta EE Developer I have not the experience to figure out the correct project structure for the GLSP concept of Sever/Client/Theia-Integration.

Can someone help me out of this yarn hell? I need an example how the glsp-theia-integration has to be used in case you don't want to test the glsp-workflow example only ;-)

My project can be seen on Github : https://github.com/imixs/imixs-bpmn.glsp

[tortmayr]

Hi @rsoika,
as a Java Developer without any previous experience with yarn/lerna repositories setting up everything correctly can be a bit tricky. Don't worry we have all been there once 😉. I will try to give you some feedback and pointers to help you get started.

First and foremost I recommend to checkout the minimal example of the glsp-examples repository. It basically outlines the minimal configuration needed to fully integrate GLSP in a Theia application and you could use the project structure as a reference template.
The master branch is still based on GLSP 0.8.0 but we are currently in the process of updating the example repository. It should be ready to merge soon, in the meantime you could have a look at the minimal directory in the PR-branch

In the GLSP project we use a combination of lerna and the yarn workspaces feature to manage and link multiple local packages in a so called monorepository. If everything is setup correctly there should be no need for manual linking.

I had a quick look at your source code and the problem with your current project structure is that the glsp-client and glsp-theia are configured as two separated lerna repositories that don't know each other. That's why your theia-integration cannot resolve the dependency to @imixs-bpmn/bpmn-glsp.

To solve this issue you have to combine all packages in one lerna repository (directory).
As a first step I would recommend to clean up your current project. I noticed that you have a local copy of the generic glsp packages (i.e. the contents of the packages directory) in your repository. This not necessary at all. Your package structure should only contain the bpmn specific packages. You can simply remove the other packages and rebuild. Yarn then will automatically consume the generic glsp packages (@eclipse-glsp/client, @eclipse-glsp/theia-integration) from NPM.
I suggest to restructure as like this:

• Move the workflow-theia (which should probably be named bpmn-theia) package into the glsp-client directory
• Move the browser-app into the glsp-client directory
• Remove the rest of the glsp-theia directory
• Remove the packages directory from glsp-client

So the final project structure should look like this:

myproject/
├── glsp-client
│   ├── browser-app/  
│   ├── bpmn-glsp/  
│   ├── bpmn-standalone/ 
│   └── bpmn-theia/      
│   ├── package.json
│   ├── lerna.json
│   └── ..............
├── glsp-server
│   ├── plugin.xml
│   ├── pom.xml
│   └── ..............
├── pom.xml

Then add .bpmn-theia and .browser-app to the workspaces entry of the root package.json in glsp-client (And remove the packages entry as its no longer needed).
After rebuilding, yarn should be able to resolve the dependency to @imixs-bpmn/bpmn-glsp": **"0.0.1"**.

Note: There is currently an issue with the version range of Theia dependencies in @eclipse-glsp/theia integration beeing to lose. This can cause issues with yarn because yarn might resolve transitive Theia versions that are incompatible. To avoid this issue I recommend to enforce the usage of the compatible 0.20.0 version by adding a "resultions" block to the root package.json in your glsp-client directory:

package.json

{
...
 "resolutions": {
    "**/@theia/core": "1.20.0",
    "**/@theia/editor": "1.20.0",
    "**/@theia/filesystem": "1.20.0",
    "**/@theia/markers": "1.20.0",
    "**/@theia/messages": "1.20.0",
    "**/@theia/monaco": "1.20.0",
    "**/@theia/navigator": "1.20.0",
    "**/@theia/outline-view": "1.20.0",
    "**/@theia/preferences": "1.20.0",
    "**/@theia/process": "1.20.0",
    "**/@theia/terminal": "1.20.0",
    "**/@theia/variable-resolver": "1.20.0",
    "**/@theia/userstorage": "1.20.0",
    "**/@theia/workspace": "1.20.0",
    "**/@theia/cli": "1.20.0",
    "**/inversify": "5.1.1"
  }
}

[rsoika]

@tortmayr Thanks a lot for this perfect explanation. This will help me a lot and gives me back the confidence to start once again ;-)

I was was not aware of the importance of the lerna files and (to be honest) I ignored them so far. The idea to move bmn-theia/ module into the glsp-client module makes sense and I tried it before (but without success because of the other issues)

I will follow your instructions and will give you a feedback.

One question I have in mind with the monorepository structure:
If the /glsp-client, bpmn-theia and bpmn-standalone are in one place, I expect that the yarn install will take always a long time. Even if I just want to test some minor design changes in the bpmn-standalone html page. Is it possible to instruct yarn to just build bpmn-glsp and bpmn-standalone for a fast test? Is this something which can be achieved with the "scripts": section in the package.json?

[CamilleLetavernier]

Hi,

You can always rebuild a single project, by executing yarn into this project directory (e.g. in bpmn-theia/). Of course, this is only relevant if dependencies haven't changed. When changing bpmn-glsp, you probably have to rebuild both bpmn-glsp and bpmn-standalone, in that order.

You can also use a "watch" script, to automatically rebuild projects when source code changes, which is a lost faster for quick iterations. It's a custom script added in most projects (in package.json), that can then be executed with yarn watch.

[rsoika]

I checked the updated glsp-examples from the master tree. Both examples (minimal and worklfow) work of course - thanks for the update.

I try to start again from scratch with the minimal example ..........................

[rsoika]

Finally I succeeded to setup a minimal project setup with all my own namespaces and directory structure !

The whole procedure took several hours, but now I am experienced working with yarn ;-)

(Renaming packets and folders isn't something yarn takes lightly... this was a steep learning curve)