aion-plugin

An app using dumber bundler to build. More details in gulpfile.js.

Run in dev mode, plus watch

npm start

To clear cache

Clear tracing cache. In rare situation, you might need to run clear-cache after upgrading to new version of dumber bundler.

npm run clear-cache

Aurelia Plugin Structure

This Aurelia plugin project has a built-in dev app to simplify development.

1. The local src/ folder, is the source code for the plugin.
2. The local dev-app/ folder, is the code for the dev app, just like a normal app bootstrapped by aurelia-cli.
3. You can use normal npm start and npm test in development just like developing an app.
4. You can use aurelia-testing to test your plugin, just like developing an app.
5. To ensure compatibility to other apps, always use PLATFORM.moduleName() wrapper in files inside src/. You don't need to use the wrapper in dev-app/ folder as dumber bundler supports module name without the wrapper.

Resource import within the dev app

In dev app, when you need to manually import something from the inner plugin (for example, importing a class for dependency injection), just use import {...} from "../src/path/to/resource";.

Note this is different from the plugin project generated by aurelia-cli, where users need to use special name "resources" to reference the inner plugin. That unintuitive special name was designed to bypass limitation of RequireJS and SystemJS. Dumber bundler's AMD module loader (dumber-module-loader) has no such limitation.

Manage dependencies

By default, this plugin has no "dependencies" in package.json. Theoretically this plugin depends on at least aurelia-pal because src/index.ts imports it. It could also depends on more core Aurelia package like aurelia-binding or aurelia-templating if you build advanced components that references them.

Ideally you need to carefully add those aurelia-pal (aurelia-binding...) to "dependencies" in package.json. But in practice you don't have to. Because every app that consumes this plugin will have full Aurelia core packages installed.

Furthermore, there are two benefits by leaving those dependencies out of plugin's package.json.

1. ensure this plugin doesn't bring in a duplicated Aurelia core package to consumers' app. This is mainly for app built with webpack. We had been hit with aurelia-binding v1 and v2 conflicts due to 3rd party plugin asks for aurelia-binding v1.
2. reduce the burden for npm/yarn when installing this plugin.

If you are a perfectionist who could not stand leaving out dependencies, we recommend you to add aurelia-pal (aurelia-binding...) to "peerDependencies" in package.json. So at least it could not cause a duplicated Aurelia core package.

If your plugin depends on other npm package, like lodash or jquery, you have to add them to "dependencies" in package.json.

Build Plugin

Run npm run build. This will transpile all files from src/ folder to dist/.

For example, src/index.ts will become dist/index.js.

Note all other files in dev-app/ folder are for the dev app, they would not appear in the published npm package.

Consume Plugin Privately

By default, the dist/ folder is not committed to git. (We have /dist in .gitignore). But that would not prevent you from consuming this plugin through direct git reference.

You can consume this plugin directly by:

npm i github:your_github_username/aion-plugin
# or if you use bitbucket
npm i bitbucket:your_github_username/aion-plugin
# or if you use gitlab
npm i gitlab:your_github_username/aion-plugin
# or plain url
npm i https:/github.com/your_github_username/aion-plugin.git

Then load the plugin in app's main.ts like this.

aurelia.use.plugin('aion-plugin');
// for webpack user, use PLATFORM.moduleName wrapper
aurelia.use.plugin(PLATFORM.moduleName('aion-plugin'));

The missing dist/ files will be filled up by npm through "prepare": "npm run build" (in "scripts" section of package.json).

Yarn has a bug that ignores "prepare" script. If you want to use yarn to consume your plugin through direct git reference, remove /dist from .gitignore and commit all the files. Note you don't need to commit dist/ files if you only use yarn to consume this plugin through published npm package (npm i aion-plugin).

Publish npm package

By default, "private" field in package.json has been turned on, this prevents you from accidentally publish a private plugin to npm.

To publish the plugin to npm for public consumption:

1. Remove "private": true, from package.json.
2. Pump up project version. This will run through npm test (in "preversion" in package.json) first.

npm version patch # or minor or major

3. Push up changes to your git server

git push && git push --tags

4. Then publish to npm, you need to have your npm account logged in.

npm publish

Automate changelog, git push, and npm publish

You can enable npm version patch # or minor or major to automatically update changelog, push commits and version tag to the git server, and publish to npm.

Here is one simple setup.

1. npm i -D standard-changelog. We use standard-changelog as a minimum example to support conventional changelog.

• Alternatively you can use high level standard-version.

2. Add two commands to "scripts" section of package.json.

"scripts": {
  // ...
  "version": "standard-changelog && git add CHANGELOG.md",
  "postversion": "git push && git push --tags && npm publish"
},

3. you can remove && npm publish if your project is private

Cypress e2e test

All e2e tests are in cypress/integration/.

Run e2e tests with:

npm run test:e2e

Note the test:e2e script uses start-server-and-test to boot up dev server on port 9000 first, then run cypress test, it will automatically shutdown the dev server after test was finished.

To run Cypress interactively, do

# Start the dev server in one terminal
npm start
# Start Cypress in another terminal
npx cypress open

For more information, visit https://www.cypress.io