Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for creating plugins #658

Closed
simonfox opened this Issue Jun 20, 2017 · 33 comments

Comments

Projects
None yet
@simonfox
Copy link
Contributor

simonfox commented Jun 20, 2017

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

This comment has been minimized.

Copy link
Member

JeroenVinke commented Jun 20, 2017

@AshleyGrant we spoke about this, right?

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

@AshleyGrant

This comment has been minimized.

Copy link
Member

AshleyGrant commented Jun 20, 2017

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

This comment has been minimized.

Copy link
Member

jwx commented Jun 20, 2017

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

This comment has been minimized.

Copy link
Contributor Author

simonfox commented Jun 20, 2017

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

This comment has been minimized.

Copy link
Member

EisenbergEffect commented Jun 20, 2017

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

@simonfox

This comment has been minimized.

Copy link
Contributor Author

simonfox commented Jun 21, 2017

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

@EisenbergEffect

This comment has been minimized.

Copy link
Member

EisenbergEffect commented Jun 21, 2017

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

This comment has been minimized.

Copy link

manuel-guilbault commented Jul 1, 2017

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

This comment has been minimized.

Copy link
Member

JeroenVinke commented Jul 4, 2017

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

@EisenbergEffect

This comment has been minimized.

Copy link
Member

EisenbergEffect commented Jul 4, 2017

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

This comment has been minimized.

Copy link

cottrellio commented Aug 2, 2017

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

This comment has been minimized.

Copy link

xdvarpunen commented Sep 27, 2017

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

@JeroenVinke

This comment has been minimized.

Copy link
Member

JeroenVinke commented Sep 28, 2017

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

@manuel-guilbault

This comment has been minimized.

Copy link

manuel-guilbault commented Sep 28, 2017

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

@cottrellio

This comment has been minimized.

Copy link

cottrellio commented Nov 2, 2017

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

@manuel-guilbault

This comment has been minimized.

Copy link

manuel-guilbault commented Nov 3, 2017

@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

This comment has been minimized.

Copy link

jmdavid commented Feb 1, 2018

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

@manuel-guilbault

This comment has been minimized.

Copy link

manuel-guilbault commented Feb 2, 2018

@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

This comment has been minimized.

Copy link
Member

Alexander-Taran commented Mar 24, 2018

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

@jvalst

This comment has been minimized.

Copy link

jvalst commented Nov 1, 2018

Any news on this?

@zewa666

This comment has been minimized.

Copy link
Member

zewa666 commented Nov 1, 2018

@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

@huochunpeng

This comment has been minimized.

Copy link
Member

huochunpeng commented Nov 1, 2018

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

This comment has been minimized.

Copy link
Member

EisenbergEffect commented Nov 2, 2018

@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

This comment has been minimized.

Copy link
Member

JeroenVinke commented Nov 2, 2018

I think we can continue with #793

@EisenbergEffect

This comment has been minimized.

Copy link
Member

EisenbergEffect commented Nov 2, 2018

Good call @JeroenVinke I forgot about that PR.

@CuddleBunny

This comment has been minimized.

Copy link

CuddleBunny commented Feb 5, 2019

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

This comment has been minimized.

Copy link
Member

fkleuver commented Feb 5, 2019

@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: aurelia/aurelia#328 (comment)

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.

@huochunpeng

This comment has been minimized.

Copy link
Member

huochunpeng commented Feb 5, 2019

@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

This comment has been minimized.

Copy link

CuddleBunny commented Feb 6, 2019

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.

@huochunpeng

This comment has been minimized.

Copy link
Member

huochunpeng commented Feb 6, 2019

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

This comment has been minimized.

Copy link
Contributor

avrahamcool commented Feb 11, 2019

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?)

@huochunpeng

This comment has been minimized.

Copy link
Member

huochunpeng commented Feb 11, 2019

give the option to customize publishing

Good idea.

@huochunpeng huochunpeng referenced this issue Mar 22, 2019

Merged

feat: scaffolding aurelia plugin project #1075

3 of 3 tasks complete

huochunpeng added a commit to huochunpeng/cli that referenced this issue Mar 22, 2019

@huochunpeng

This comment has been minimized.

Copy link
Member

huochunpeng commented Mar 22, 2019

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.

huochunpeng added a commit to huochunpeng/cli that referenced this issue Mar 25, 2019

huochunpeng added a commit to huochunpeng/cli that referenced this issue Mar 27, 2019

huochunpeng added a commit to huochunpeng/cli that referenced this issue Mar 27, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.