Add generator for example VS Code extension

[planger]

The added example is called Hello World (VS Code extension) and produces a Theia application with a small example VS Code extension as part of the application. This shall demonstrate the second extension mechanism of Theia, ie via VS Code extensions alongside Theia extensions.

See also https://github.com/eclipse-theia/theia-website/issues/316

The created application is set up for developing and building the VS Code extension alongside other VS Code or Theia extensions in the same mono repo by linking the VS Code extension in a plugins folder of the Theia application. Also, this setup enables debugging the included VS Code application.

Lastly, this change extends the generator to optionally (option -p)

• include the Theia extension required for the plugin mechanism to work
• create a plugins folder that shall contain the plugins
• extend the launch scripts and launch.json to set the plugins folder

Please note that this change contains code in templates/vscode-hello-world/extension.ts copied from https://github.com/microsoft/vscode-extension-samples/tree/main (MIT License). I think it is very minimal, just a few lines. But it may still require a CQ.

Contributed on behalf of STMicroelectronics.

[planger]

@vince-fugnitto Thanks for the fast feedback!

Imho there are two use cases:

1. Developers create a VS Code extension for VS Code that they also may want to use in Theia. For this use case, I'd absolutely agree. Those would use the VS Code extension generator and develop and test it against VS Code, and eventually also test and deploy it in a Theia application.
2. Developers choose the VS Code extension mechanism to develop certain functionality in a Theia application. They possibly do that alongside other Theia extensions. So they would want to have those VS Code extensions as part of their Theia application mono repo and develop, test, and debug against their target Theia application. For this use case, there is currently no documentation or an example on how to do that, even though this is one of the two extension mechanism Theia promotes.

This PR addresses the use case no. 2 and is intended to act as an example for the upcoming documentation on extending Theia with VS Code extensions.

In my experience of Theia projects, I feel that this second use case is very often overlooked and people tend to resort to Theia extensions by default. In many cases this makes a lot of sense (as they are more powerful, easier to develop UIs, etc.). However, in other cases, developing a VS Code extension instead may be a great choice, also if you don't intend it to be used primarily in VS Code, but in a custom Theia project (e.g. for tree views, language contributions, debuggers, special build commands, etc.).

[vince-fugnitto]

2. Developers choose the VS Code extension mechanism to develop certain functionality in a Theia application. They possibly do that alongside other Theia extensions. So they would want to have those VS Code extensions as part of their Theia application mono repo and develop, test, and debug against their target Theia application. For this use case, there is currently no documentation or an example on how to do that, even though this is one of the two extension mechanism Theia promotes.

@planger wouldn't the documentation be sufficient? It is not a request I've seen in our forums or community, and the idea would just be to use the more feature rich yo code generator in the monorepo if necessary. Given that this repo is for creating theia extensions doesn't the generation of vscode plugins feel out of place? (else we'd need to rename the repo and the generator itself).

[planger]

@vince-fugnitto I guess, we could make it work by just documentation. There are a few details, however, which I believe are cumbersome to get right just from documentation + VS Code extension generator, especially for beginners (e.g. npm vs yarn, integration in a Theia app mono repo, getting debugging up and running, sharing a tsconfig with Theia extensions, etc.). With an example generator like this, the actual documentation could be very brief by pointing to the generator, explaining the pieces of this example and pointing to the VS Code API docs for enhancing the example.

Anyway, if you are against this PR, I'll try enhancing my WIP for the documentation page addressing https://github.com/eclipse-theia/theia-website/issues/316.

[planger]

@vince-fugnitto No no, that's fine, thanks, you are making valid points! Based on your arguments I'm open to both, deciding that it isn't a good fit here or considering to merge it. I just wanted to clarify my original motivation to propose this generator in the generator-theia-extension.

In general, I think the option of developing VS Code extensions for certain requirements of a Theia application (also if VS Code is not an immediate deployment target) is often underrated and should imho be promoted. But this surely can also be done with plain documentation too.

I'll try to propose a documentation page for https://github.com/eclipse-theia/theia-website/issues/316 that is standalone (without piggybacking this PR) and we can then judge whether it is enough? What do you think?

Thanks again for your detailed feedback!

[msujew]

My 2 cents here: I agree with Vince. While it's a good idea to show how to integrate Theia with other related web-technologies, we shouldn't try to emulate features which are already done better by the vscode generator. Having good documentation which we can refer to if someone has questions is arguably the better solution.

[planger]

@vince-fugnitto @msujew Thanks again for your feedback! I certainly understand your points. :+1:

I've opened a PR for the theia website that adds a "standalone" documentation on authoring VS Code extensions in the context of a Theia app. It'd be great if you could give me your feedback whether you think that's good enough without an accompanying generator or example.

If yes, let's not add the generator added in this PR. If you'd find it useful, I'm offering to remove the generator from this PR and only keep the additional option (-p) for generating the plugins folder and configs? WDYT?

Thanks again!

[JonasHelming]

I am actually in favor of having this generator. It is basically a very simple way of getting a custom VS Code extension running in Theia. I would love to use this in trainings, demos and presentations.

I agree that we should not duplicate "yo code" and that this PR has less options. However, the purpose of this generator is not to create an arbitrary VS Code extension, but demonstrate how a project with a simple VS Code extension in Theia could look like. It is also great to have documentation on this. But to try things out, a generator always removes an extra step to take.

I am viewing this from a marketing POV. Getting new interested adopters in a state that they start to develop/try something in a workspace is from my POV very essential goal. This should be as easy as possible. If I am a former VS Code extension developer, reading the docu only might already make me loose my interest. If i can create a simple "hello world", I can see within a minute that the VS Code extension is running in Theia, the code looks familiar and I can start to play around.

We offer this experience for Theia extensions, but not for VS Code extensions.

So I would be in favor of adding this. However, I would add a clear mesage to the Readme and also on the command line that references to "yo code" like: "This generator only creates a simple hello world VS Code extension. If you want to create other types of VS Code extensions with more options, please use the VS Code extension generator and refer to this documentation on how to integrate them into your Theia-based product."

[vince-fugnitto]

@JonasHelming please see my feedback at https://github.com/eclipse-theia/generator-theia-extension/pull/155#pullrequestreview-1089277503 if you haven't already. I'm not sure it makes senses to include a vscode plugin generator within yo theia-extension, we are ultimately mixing concepts.

It is basically a very simple way of getting a custom VS Code extension running in Theia. I would love to use this in trainings, demos and presentations.

You can always have an example repository of it already setup for such purposes, but including it in the generator might seem odd.

[JonasHelming]

@JonasHelming please see my feedback at #155 (review) if you haven't already. I'm not sure it makes senses to include a vscode plugin generator within yo theia-extension, we are ultimately mixing concepts.

I have and I see your points. I agree it would be "cleaner" to have a separate generator for every extension type. However, this is about visibility, maintenance and simplicity for the users. People who start the generator will see that there is also the option to use a VS Code extension no matter what path they come from. Vs Code always maintains one generator for various types of extensions. The main inconsistency is that the name of the generator is "theia-extension". I can live with it, we might also just rename that to "yo theia" in the future to remove the inconsistency.

It is basically a very simple way of getting a custom VS Code extension running in Theia. I would love to use this in trainings, demos and presentations.

You can always have an example repository of it already setup for such purposes, but including it in the generator might seem odd.

This is true for all templates we currently have, but I would claim it is much less maintenance to host them here in the generator due to their shared files. Also, I am not saying doing demos, trainings and presentations is the only justification for this. It is really enabling somebody to get a VS Code extension in a Theia based product within a minute.

Anyways, thank you for raising your valid concerns. I will add this to the dev call agenda to see what other people thing.

[sdirix]

We recently discussed the Theia generators in the Dev Meeting and concluded that maintaining a single generator instead of multiple ones is the way forward, potentially under the new name yo theia. Therefore having this generator makes sense again.