feat: scaffolding aurelia plugin project

[3cp]

This enables au new --plugin (or au new project-name --plugin) to scaffold an Aurelia plugin project. Closes #658.

You can start testing this feature now with command

npx huochunpeng/cli#scaffold-plugin new --plugin

The README.md file in the generated project has more explanation on the project structure.

TODO

• update generate-skeletons to cover plugin skeletons
• update release-check to cover plugin skeletons
• run through release-check

[hanssens]

After I noticed the PR, immediately wanted to give it a go. I was up and running in no-time (smart choice mentioning the upx command)! Some early feedback with the TypeScript variant:

• It wasn't quite clear from the README that I needed to register my custom elements in ~/src/index.ts, in order for it to be picked up in the dev-app.
• styling for .scss/.css doesn't seem supported (or output) yet?

As a side note I want to definitely say that I'm really happy with this PR! Although I've only looked at it functionally, from developer/consumer perspective, the ability to create a simple plugin skeleton that handles the tough build elements is something I've been waiting a long time for. Hands down, for me one of THE most important features to hopefully get more users onboard with Aurelia. Or, at least, enrich the ecosystem in an easy and conventional way.

Great work so far!

[3cp]

@hanssens appreciated!
I will update the readme for more guide on writing aurelia plugin. We will add plugin guide to our official doc site as well.
For scss, if you choose "sass" in the questionnaire when creating your project, you will be able to write foo.scss file and use <require from="./foo.css"></require> in your foo.html.

There is one thing I forgot in this PR. You need to move all your "dependencies" to "devDependencies" in package.json.

[3cp]

@EisenbergEffect for simplicity, what do you think about moving following two packages from "dependencies" to "devDependencies", not only for plugin project, but also for app project?

  "dependencies": {
    "aurelia-bootstrapper": "",
    "aurelia-animator-css": ""
  },

[EisenbergEffect]

Seems like they should be direct dependencies for an app...

[3cp]

My argument is app is not npm package, so it does not matter where you put thoses deps. Once the app is built, it has no “runtime” dependency.

[3cp]

I will leave them in dependencies for app project. That was not an important simplification.

[3cp]

@EisenbergEffect we will need a new doc page for writing Aurelia plugin.

The plugin template readme has a link to https://aurelia.io/docs/plugins/write-new-plugin, I will compose a draft for the new guide, using cli to build plugin, covers the basics. After that, maybe some team member can jump in to enhance the guide to cover advanced topics, like registering new things to DI, using static class import (plus mandatory decorator on those classes) to load components.

[EisenbergEffect]

@huochunpeng That sounds great. Thank you for thinking of documentation 😄 Ping me on the docs PR and I'll merge it and then do an edit pass and publish. Then we can get some other team members involved to help expand it out a bit. @Vheissu has writing skills, so maybe he can jump in there.

[3cp]

Question: following our default app setup, the default plugin setup also uses jest as default unit tests framework. Should we switch the default to karma for plugin project? Since we really want browser test for plugin.

[CuddleBunny]

Everything is working great for me so far! Good work. Perhaps a sample stylesheet should be added to the component to avoid confusion for new folks? Doesn't need to utilize any feature of the selected pre-processor in my opinion.

[3cp]

@CuddleBunny I was trying that yesterday. I will add a stylesheet after I cleanup module stub to support cli-bundler+jest setup

[3cp]

@CuddleBunny css/less/scss/styl example is added to the custom element example, based on user's css preprocessor choice.

[EisenbergEffect]

@huochunpeng I just saw the docs PR. That is super awesome and very thorough. Thank you! I'll do an edit pass before publishing if that's ok with you. With that in place, are we ready to merge this PR, release the CLI and publish that documentation?

[3cp]

Not yet, I am running release-check, the slowness is killing me...

[EisenbergEffect]

No problem. Ping me when it's ready and I'll merge both this and the docs PR.

[3cp]

@EisenbergEffect passed all release-check on both windows and mac. This PR is ready for review.

Please review skeleton/plugin/README.md for the instructions, the file shared many contents with aurelia/documentation#392

The other thing is about the default choice of unit testing framework, which I asked in this thread. Should we switch default from jest to karma for plugin setup?

[EisenbergEffect]

We should probably have the default test framework be the same for apps and plugins, if possible. @huochunpeng Do you want to add that to this PR or submit it as a 2nd PR?

[3cp]

If to modify default test setup for both app and plugin, better to do another PR. We will leave it as jest for now.

It might be worth considering to switch default app from webpack+jest to cli-bundler+karma since built-in bundler is quite easy to use now.

I don't know much about the story on the default webpack+jest, more opinion is needed.

[EisenbergEffect]

I personally don't care for Jest (for various reasons), so I'd prefer to use Karma. I don't know what the rest of the community thinks about that though. Whatever we do, I think both app and plugin scaffolding should use the same thing by default.

[3cp]

We can push that decision to v1.1. Let's get a solid v1 release first.

[EisenbergEffect]

@huochunpeng Were you thinking that we'd do one more beta and then a 1.0? Or were you thinking we'd just go to 1.0 with this release.

[3cp]

Definitely one more beta, with potential bugs to be fixed before v1.
Plugin scaffolding is the last todo on v1 list, unless you have other feature in mind.

[EisenbergEffect]

I'm pretty happy with this feature set :) Going 1.0 soon is also good timing for vNext. After it's out, we can start to look at CLI 2.0 as supporting vNext AoT and related scenarios.

[michaelw85]

@huochunpeng @EisenbergEffect

I recently made the choice to go with jest in our default setup at work.
The reasons I chose jest over karma+webpack & my experience so far:

• Jest performance is very good
• Mocks in Jest are incredibly powerful, you could share mocks easily between projects and use mocks from the community. You do not have to setup your mocks within a test, you could choose to put mocks in mocks folders keeping your tests very clean.
• Jest is actively maintained, I was very surprised about the speed when I provided a small PR, updating the docs. PR was almost instantly picked up, reviewed and after a couple iterations merged and published. I did not take more than an hour I think.
• I have a setup with Jest + pre commit hooks, on commit touched files will have their related tests run (this is awesome imo!) Spend less time waiting for build output and less builds needed.
• Jest + TS has very good support, easy to setup
• I personally haven't used it yet but Jest comes with snapshot support, this sounds very interesting to me to be able to render components, take a snapshot of the dom and test against that data.
• Jest has a very nice watch mode allowing you to write code and automatically run tests related to the code touched. It has more options that are really useful like watch mode to only run failed tests which makes BDD very easy.
• less configuration needed (for code coverage, I spent quite some time in webpack/karma config gettings things setup in the past and I feel this is a waste of time. I should be writing code/tests not spend loads of time configuring my tools to work as expected)
• Jest can be used for code that does not run in the browser, node only code.

I'm very happy with Jest so far, I struggled a bit with mocks at the start and had an issue with aurelia+scss but that's resolved now.
Hope this info helps a bit in making a choice.

[zewa666]

For a DOM intense plugin, e.g I18N, typically Karma would be preferred. But with recent updates I made the switch to Jest as well. The thing is that Jest is neither the fastest nor the perfect deal for DOM based testing (JSDOM) but the support and ease-of-use is definitely so much better that its often worth the reduced feature set. One has to keep in mind though that tons of things have to be polyfilled for such cases.

Since I expect most plugins being not too DOM intensive, I'd also argue jest is a fine default. If someone really needs to do more, doing a manual shift to Karma shouldn't be impossible.

[hanssens]

For what it's worth: another community-based +1 for Jest on behalf of me and my team. We switched to Jest a while ago, because of the aforementioned "ease-of-use". The convention-based, all-in-one setup is easy to start with and pretty much suits most basic needs out of the box.

What was cumbersome with Karma is that we quickly had to rely on additional frameworks/libs like Mocha/Jasmine etc. for a full test experience.

[3cp]

I am no fan of cumbersome karma either. But I like real browser. Personally I pipe bundled tests code directly to browser-run.

[EisenbergEffect]

@huochunpeng I can merge and release this today with the documentation update happening either today or tomorrow. Do you feel it's ready or do you want a specific person to do additional review before we move ahead?

[3cp]

It is ready for me. :-)

[CuddleBunny]

I've been using it, seems pretty solid to me. Great work!

[kennyfowler]

sorry for commenting on a closed issue, but its a minor suggestion and I'm not sure if its worth an issue:

In a scaffolded typescript plugin project, I cannot import any exported members from the plugin in the dev app, because typescript cannot know the plugins module-name.

Putting a path alias in tsconfig.json would solves this

{
  "compilerOptions": {
	"baseUrl": "src", // already there
	"paths": {
		"resources": [ "" ] // relative to baseUrl, using 'resources' like in aurelia.json
	}
  }
}

Now I can import any exported members from the plugin in the dev app:

import { PluginConfiguration } from 'resources'

...and something noteworthy: I had some problems testing the dev app in the browser because window.process was missing. There is a hint in the docs about mocking this https://aurelia.io/docs/cli/cli-bundler/dependency-management#auto-tracing

import process from 'process';
window.process = process;

And big thanks to this great feature!

[3cp]

Thx @kennyfowler do you want to make a PR for that?

[kennyfowler]

@huochunpeng yes, I will do

[3cp]

@kennyfowler if you don't mind, I used and acknowledged your fix in #1085