Add generator for example VS Code extension #155
Conversation
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. 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 Contributed on behalf of STMicroelectronics.
There was a problem hiding this comment.
@planger I do not fully understand why we want to mix concepts and add a vscode extension generator to our theia extension generator, developers should use the vscode extension generator directly which has better tooling, and more examples.
I'd like it to be clarified before we go further.
|
@vince-fugnitto Thanks for the fast feedback! Imho there are two use cases:
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.). |
@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 |
|
@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 eclipse-theia/theia-website#316. |
There was a problem hiding this comment.
@planger I don't want to block the pull-request but I'm just not sure its appropriate in this repository, for instance:
- the generator is meant to generate theia extensions since they can be quite tricky but is now also used to generate vscode plugins which may or may not fit (we don't for instance generate theia plugins here) and its not clear that
yo theia-extensionwould generate a vscode plugin. - we only have a subset of what
yo codehas in terms of templates (ex: themes, language-support, ...) - we do not have their test files generated by the repository.
- we lose vscode's bundling with webpack already supported by
yo code. - we make the decision for plugin developers to use
yarnbut they should be free to use whatever they like includingnpmas they do not need to re-use theia's configs the same way that extensions do in order to work (this is another example of mixing concepts).
| module.exports = { | ||
| activate, | ||
| deactivate | ||
| } |
| "name": "<%= params.extensionName %>", | ||
| "displayName": "Hello World (VS Code extension)", | ||
| "engines": { | ||
| "vscode": "^1.32.0" |
There was a problem hiding this comment.
Why are we targetting such an old vscode version, should it not at least match our currently supported api version v1.53.2?
| "rimraf": "latest", | ||
| "typescript": "latest" | ||
| } | ||
| } |
| "symlink": "symlink-dir . ../plugins/<%= params.extensionName %>" | ||
| }, | ||
| "devDependencies": { | ||
| "@types/vscode": "^1.32.0", |
There was a problem hiding this comment.
Same as engines.vscode question.
| @@ -0,0 +1 @@ | |||
| *.vsix | |||
|
@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 eclipse-theia/theia-website#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! |
|
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. |
|
@vince-fugnitto @msujew Thanks again for your feedback! I certainly understand your points. 👍 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. Thanks again! |
|
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." |
|
@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
You can always have an example repository of it already setup for such purposes, but including it in the generator might seem odd. |
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.
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. |
|
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 |
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 eclipse-theia/theia-website#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
pluginsfolder of the Theia application. Also, this setup enables debugging the included VS Code application.Lastly, this change extends the generator to optionally (option
-p)pluginsfolder that shall contain the pluginsPlease note that this change contains code in
templates/vscode-hello-world/extension.tscopied 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.