Support for creating plugins

[simonfox]

After a brief Gitter discussion I thought it might be worth starting a discussion here. The idea is to support something like au new --plugin or au new-plugin which would output something like https://github.com/aurelia/skeleton-plugin.

Has this already been discussed? Is there interest in adding a feature like this? I could probably start looking at it if there is.

[JeroenVinke]

@AshleyGrant we spoke about this, right?

Could we maybe add support for yeoman so that we can define skeletons outside of the CLI?

[AshleyGrant]

Yeah, I believe we talked about this last week at the Aurelia Amsterdam meetup. I'm not sure we necessarily need to use yeoman. We could have a new repo that includes folders for different types of skeletons maybe.

But that being said, I'm not sure we currently want to move the CLI toward creating skeletons. Currently it creates a barebones application, versus the skeletons which have sample code and more dependencies. Maybe the initial implementation could be a barebones plugin.

[jwx]

I think support for a barebone plugin through some variation of au new is a good idea.

As for creating skeletons, I'm still in favour of my previous au skeleton suggestion. But I believe the au feature that I've talked about would be an even better addition than skeletons.

[simonfox]

The intention was not to create a skeleton with sample code, but just a minimal setup for creating a plugin. The only source that would likely be included would be something like

//index.js
export function configure(config) {
  //config.globalResources('');
}

but the build pipeline and dependencies would all be setup and ready for dev.

The issue discussed on gitter was that for some one who is not familiar or comfortable with gulp, taking the pieces from an au new typecript project and pieces from skeleton-plugin to get started on a typescript plugin implementation was a little daunting.

I don't know the nitty gritty of yeoman but it could be one option, although the output would still need to be useable with au. I'm not sure of the benefit of yeoman when the cli already has a bunch of code that could be reused to achieve this?

[EisenbergEffect]

We should definitely enable au new --plugin but we need to get a few other pieces in place first :)

[simonfox]

@EisenbergEffect what were those pieces specifically if I had time to help out here?

[EisenbergEffect]

Mainly, we need to get the Webpack support merged in, enable asp.net, switch our defaults to webpack and implement the "eject" capability probably. After that we can add the plugin generate support and then move on to Electron and Cordova.

[manuel-guilbault]

I'd be interested in contributing on this feature, so let me know how I can help.

Also, I created an empty TypeScript plugin skeleton. It looks pretty much like the official skeleton-plugin, but it's written in TypeScript instead of ES2017. It is based on both Dwayne Charrington's aurelia-typescript-plugin and the official validation plugin. I created it mostly because Dwayne's version uses Jest instead of Jasmine. Maybe it could be useful as a model for the TypeScript version of this feature.

[JeroenVinke]

@EisenbergEffect See above comment. What are your thoughts on this feature? I can help @manuel-guilbault in implementing it.

[EisenbergEffect]

I'd love to be able to do au new --plugin. If @manuel-guilbault wants to work on it, that would be great. We want to try and set these up with some boilerplate that helps people get their plugins correct for require.js, system.js and webpack if possible.

[cottrellio]

Coming from Ember, I can't think of another feature that would build the Aurelia community faster than having a cli command for generating a plugin! Especially if it's like the current au new that allows you to choose webpack, typescript, etc.

[xdvarpunen]

@manuel-guilbault @JeroenVinke how is plugin project going?

[JeroenVinke]

@manuel-guilbault is making some great progress. We're currently working on getting the unit testing setup right

[manuel-guilbault]

@xdvarpunen @JeroenVinke hopefully I'll be able to get it done in the upcoming weeks

[cottrellio]

Any update on this @manuel-guilbault? No pressure, just super excited! :D

[manuel-guilbault]

@cottrellio I have a hard time freeing up my schedule to work on this, it's super hot at work right now :( I'm a bit frustrated that I can't make this progress as fast as I would like. Once the pressure lightens a bit, I'll be back on it and keep you guys posted.

[jmdavid]

Thanks for great work @manuel-guilbault! I used your skeleton successfully. Do you have any update on the status of CLI generation?

[manuel-guilbault]

@jmdavid I submitted a pull request which was reviewed; now I need to do some refactoring to reduce code duplication as per Rob's feedback. I'll get to it as soon as I have a couple of free days :)

[Alexander-Taran]

for all those seeking here is a thread on discourse aurelia plugin starter kits

[KentuckyMC]

Any news on this?

[zewa666]

@huochunpeng had a fantastic way of using the aurelia-cli for both the plugin and a Dev sample at the same time. Once he's back from vacation I'd definitely like to review that and make it part of the cli

[3cp]

My way is documented here https://github.com/aurelia-contrib/aurelia-getting-started/blob/master/guides/how-to-use-cli-to-develop-plugin.md

It is different from any plugin skeletons you saw before, but I think my way is intuitive and specially great on writing test.

I wound love to gather some feedbacks, and whether it makes sense to be included in cli.

[EisenbergEffect]

@huochunpeng I'd love to have built-in support for creating and building plugins from our CLI. It's a long-time feature request from the community. If you look in the aurelia.json file, there's a type property with a value of "project:application". I had always hoped we could add support for "project:plugin".

[JeroenVinke]

I think we can continue with https://github.com/aurelia/cli/pull/793

[EisenbergEffect]

Good call @JeroenVinke I forgot about that PR.

[CuddleBunny]

After visiting this issue every couple months for over a year I think it is time to give this a shot myself. #793 goes a long way towards implementing this but as discussed in the PR there is a significant amount of duplication present. I think that duplication could be significantly reduced by using the approach outlined by @huochunpeng since it would then be practical to keep most of the existing setup the same.

All that said I get the feeling that the team has probably discussed this feature at great length outside of this thread and I would like to nail down some concrete requirements based on consensus rather than my own personal bias.

I will be the first to jump down the rabbit hole with a few questions:

What is the ideal workflow? Ideas include: au new --plugin plugin-name or the ability to build a plugin from a feature folder in an existing application project. We could probably even achieve both options but writing elegant building/bundling solutions for the possible scenarios (plugin project, application project with one or more plugins, allow for something like au generate plugin?) for all of the potential tools supported may be a little outside my wheelhouse.

Any convention for project structure? It makes sense to put the plugin code in src and output to dist to mirror the application setup. Where should the live testing environment live? Perhaps it could be placed in an examples folder and serve a self-documenting dual purpose?

Output? I've heard conflicting information about whether a plugin needs to output to AMD, UMD, and CommonJS or just CommonJS. I don't know much about how all this works behind the scenes but I imagine I will need to know in order to write the build tasks.

Reservations for vNext? Is it even worth doing this now with vNext on the horizon? How might plugins diverge from vCurrent? Will vNext share this same CLI with vCurrent and should any special care be taken to support both?

I look forward to hearing what everyone thinks.

[fkleuver]

@CuddleBunny Thanks for writing this up. A few things come to mind when I read your comment:

What is the ideal workflow?

I don't think there is any. There are vastly different needs and what is ideal for one is the worst possible thing for the other. Thinking about this from a normal API point of view, and then later translating it to a CLI interface could make things easier. Scaffolding is a hard problem to solve. There are many tools out there doing a great job and they always have tremendous shortcomings in some ways, especially if they try to provide a full out-of-the-box working template.

I believe a relatively future proof approach would be to think about which loose parts you can let the cli scaffold/generate, and they wouldn't necessarily need to be tied to being an app or a plugin. Then you can also use the tool to generate additional common pieces of boilerplate in an already ongoing project, with various "strategies" to pick from on how to deal with "merge conflicts".

What's needed to start with that is either a long list of commonly desired building blocks, or to simply build a plugin from scratch and then trying to reproduce each step of that in an automated manner, then adding it as a feature to the cli. Just an idea.

Any convention for project structure?

Also see this comment: https://github.com/aurelia/aurelia/issues/328#issuecomment-454634008

TLDR: there is the feature-based separation and the layer/type-based separation. They can also be combined (nested) for larger projects. Sometimes one makes more sense, sometimes the other. Having 2x2=4 variants to pick from seems like something that could cover most needs.

Output?

I think esm, umd and systemjs cover most if not all. Fortunately it's trivial to have these various outputs as it's just a small aspect of configuration.

Reservations for vNext?

vNext is also going to need CLI and this is why I think the modular approach would be important to try, as it allows for a lot of pieces to be reusable between both versions of Aurelia.

[3cp]

@CuddleBunny thank you very much for your thoughts on this.

For vCurrent, in addition to @fkleuver's response:

Any convention for project structure? I like the idea to keep plugin code in src and test dev app in other folder. But it could complicate the bundler config little bit. We just need to make sure to not confuse end users on both structure and config.

[CuddleBunny]

Thanks @fkleuver and @huochunpeng. I guess this bit on structure needs broken out into a few different areas: generated project structure, plugin structure, and CLI project structure.

On Project Structure I can see having separate folders being a bit confusing for the bundler and perhaps even the end user. This seems to boil down to using one of two approaches, at least for starters:

├── aurelia-cli-project
│   ├── dist
│   ├── examples
│   ├── src

au run - build and run Aurelia app(s) in examples that depend on the plugin in src.
au build - build the plugin in src

vs.

├── aurelia-cli-project
│   ├── dist
│   ├── src
│   │   ├── resources

au run/au build - same as application project
new command like au package plugin? - build plugin from src/resources

Option 1 has clear separation but decouples the build and run commands which may be counterintuitive. Option 2 doesn't require any changes to existing commands but may require a new command to help users package their plugins for distribution.

On Plugin Structure I think this should stay relatively simple and unopinionated like the application template. Something along these lines:

https://gist.github.com/CuddleBunny/a4a51c6f02a27f0219eda3ba4310e307

On CLI Project Structure I've been digging through this and it seems very flexible. Everything has its place so I don't think we need to talk much through this.

[3cp]

Yes, option2 is what's in my original tutorial as it requires the least change. When I say I like your idea, I mean I lean towards option1, just need to make sure the cli generated config is easy for user to understand.

[avrahamcool]

I think option 2 is very intuitive. It works well with the current cli structure - so no additional leaning curve is required.

having a new command for packaging the plugin is a big PLUS in my opinion. it lets build/run to behave identically to what we are used to, and give the option to customize publishing (maybe we can publish to npm directly from the cli?)

[3cp]

give the option to customize publishing

Good idea.

[3cp]

The PR #1075 uses option1, it has dedicated folder dev-app/ for the app, in order to keep all plugin sources under src/. The README.md in generated project has more explanations.

Please help to play the PR. If the option1 (separate dev app and src folder) is confusing, we can revert to option2 (src/ for dev app, and src/resources for plugin code) which is easier to implement.