A new plugin skeleton with fully automated releasing and github pages

Framework Knowledge
1

I worked out a few things as I was building my own first plugin and decided to extract the reusable bits into a new plugin skeleton so others can use it too.

Here’s the link with freshly added instructions: https://github.com/fkleuver/aurelia-plugin-skeleton-ts-webpack

This skeleton addresses/offers a few things that I missed in the original TypeScript plugin skeleton (which by the way was a great starting point, though I can’t recall exactly which one).

  • Karma and webpack configuration in TypeScript
  • Karma unit tests running with webpack 4 (fast!)
  • Accurate, source-mapped code coverage that shows word-for-word which pieces of code are covered by tests or not
  • Debug TypeScript code from the unit test runner directly in VS Code
  • An integrated test/demo app to directly test the plugin in during development
  • A clean package.json with short scripts that defer to more robust + configurable nps scripts in package-scripts.js
  • A single script to build the demo app and get it published to github pages (github has the convention of automatically creating a page for you with whatever is on the gh-pages branch)
  • A single script to test, build, bump the version, push (to github) and publish (to npmjs)
    (with a dry-run option of course)

All in all I’ve found this help me do more frequent, small incremental releases. Even simply updating the readme and making sure it’s visible on npmjs isn’t out of the question. A quick npm run publish-patch is only a few seconds work.

If any step in the process fails (test, build, w/e) the whole process cancels. No need to worry about publishing an inconsistent state.

The TypeScript and tslint configuration is fairly strict and opinionated, but you can easily toss that out if you don’t like it.

Feel free to give it a go, and go out there and create some plugins! :slight_smile:

10 Likes
2

Thanks for great job, it looks very nice. Unfortunately I don’t know how to use it properly :frowning:

You don’t really have any code in your Aurelia plugin, could you please add more comprehensive example? How do I import plugin in demo app? And what if plugin has some dependencies?

This is really huge pain point for me, I’ve been struggling with that for very very long time and I tried several aurelia plugin skeletons, none of them providing good solution for that. I always ended up with chicken and egg problem - in order to test plugin on demo page, I always had to publish it first, which lead into broken packages deployed on NPM :frowning:

3

Dear @fkleuver,

That is a great effort you’ve done comrade. :+1:

There were existing type script plugin skeletons out there though, good to know about them.

Here is a skeleton we used o write aurelia-toolbelt, and @vegarringdal is working on new one here which enables both eslint, for the scripts required to deploy and construct the plugin infra, and tslint, for plugin developers who want to expand aurelia community.

I wish the aurelia community get more and more benefits from all of these plugin skeletons. :smile:

1 Like
4

I personally prefer that @vegarringdal’s latest plugin and your plugin support jest as test framework, if possible :smiley:

2 Likes
5

if you need to do a new publish beta you can always use --tag to create a beta/next etc
https://docs.npmjs.com/cli/dist-tag

1 Like
6

@vegarringdal I know, but isn’t there any better way? @fkleuver’s skeleton looks great and from the first look it looks it could solve that chicken-and-egg problem. I just don’t know how to use it :frowning:

7

If the dependency is a js lib you import, it usually picked up by bundlers if you allow them. For css/html/ unlinked modules like query, classes not called by your plugin you might need to add instructions how to add the resources.
So having 1 simple skeleton app for you plugin is always useful for the end user.
You also get a verification that last update did not break something :slight_smile:
Some parts really just need to be tested from what I’ve seen, try out with webpack, cli, jspm (are people using jspm still btw) ?

1 Like
8

Hi @vegarringdal. I’ve cloned your plugin aurelia-plugin-skeleton-typescript locally, built it, ran npm link and then in my aurelia webpack app (webpack 4) ran npm link aurelia-plugin-skeleton-typescript and then initialized it main.js with aurelia.use.plugin(PLATFORM.moduleName('aurelia-plugin-skeleton-typescript')). It successfully locates the linked package and I can even set console.log’s within the plugin to see that it’s loading. However, I consistently get the error VM782 bluebird.js:4954 Error: Unable to find module with ID: aurelia-plugin-skeleton-typescript/hello-world in both my aurelia webpack app as well as a brand new aurelia CLI generated app. Do you or anyone else have any ideas why this might be?? Thanks.

9

An additional note is that I can run the package locally and test it and all works fine, within the plugin using the sample directory within the plugin itself. It’s just when I npm link the plugin that I see the aforementioned error.

10

UPDATE: I tried npm pack and then installed that package into my aurelia wepack app and it worked fine. I have NO IDEA why the module is not recognized in npm link mode.

11

@rkever

Hi, didnt have a chance to answer before now.
Looks like the most important parts work fine :slight_smile:
Never used npm pack or link so I cant give you any good answers here.

When I test a package I usually add “-next.1” behind and use npm publish --tag next
That way I get a chance to test it a few times like a user would before a release.