Write New Plugin

Introduction

Thanks to Aurelia coding convention, writing a new Aurelia Plugin is not difficult. However the setup of a new plugin project was difficult, but now you can generate a new plugin project effortlessly using Aurelia-CLI.

Setup

In this tutorial, we will use Aurelia-CLI to create a plugin project.

First, make sure you installed the latest Aurelia-CLI.

    
  npm i -g aurelia-cli
  
  

Then run command au new --plugin or au new project-name --plugin. You will be asked to provide a project name, followed by a number of options. If you aren't sure what you want, you can select one of the default ESNext or TypeScript setup in the first question. Otherwise, you can create a custom project. Simply follow the prompts.

Structure of Plugin

The plugin project created by Aurelia-CLI provides not only the plugin source itself, but also a dev app (with CLI built-in bundler and RequireJS) to simplify the development of the plugin.

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 au run and au 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 with other apps, always use PLATFORM.moduleName() wrapper in files inside src/. You don't need to use the wrapper in dev-app/ folder as CLI built-in bundler supports module name without the wrapper.

Plugin Entry

The plugin entry file is src/index.js (or src/index.ts if using TypeScript). It exports only one function called "configure".

    
  import {PLATFORM} from 'aurelia-pal';
  
  export function configure(config) {
    config.globalResources([
      PLATFORM.moduleName('./elements/hello-world')
    ]);
  }
  
  

    
  import {FrameworkConfiguration} from 'aurelia-framework';
  import {PLATFORM} from 'aurelia-pal';
  
  export function configure(config: FrameworkConfiguration) {
    config.globalResources([
      PLATFORM.moduleName('./elements/hello-world')
    ]);
  }
  
  

The configure function is called by Aurelia when end users use your plugin in their app like this:

    
  aurelia.use.plugin('your-plugin-name');
  
  

    
  aurelia.use.plugin(PLATFORM.moduleName('your-plugin-name'));
  
  

The methods you can use inside the configure function are listed in FrameworkConfiguration. globalResources can register custom elements, custom attributes, value converters, and binding behaviors to be globally available in end users' app.

Create New Resources

You can create a new custom element, custom attribute, value converter or binding behavior manually, or use command au generate to help.

    
  au generate element some-name
  au generate attribute some-name
  au generate value-converter some-name
  au generate binding-behavior some-name
  
  

By default, the cli generate command generates files in following folders:

    
  src/elements
  src/attributes
  src/value-converters
  src/binding-behaviors
  
  

Note the folder structure is only to help you with organizing the files, it's not a requirement of Aurelia. You can manually create new element (or other thing) anywhere in src/.

After you added some new file, you need to register it in src/index.js (or src/index.ts. Like this:

    
  config.globalResources([
    // ...
    PLATFORM.moduleName('./path/to/new-file-without-ext')
  ]);
  
  

Resource import within the dev app

In dev app, when you need to import something from the inner plugin (for example, importing a class for dependency injection), use special name "resources" to reference the inner plugin.

    
  import {inject} from 'aurelia-framework';
  // "resources" refers the inner plugin src/index.js
  import {MyService} from 'resources';
  
  @inject(MyService)
  export class App {
    constructor(myService) {
      this.myService = myService;
    }
  }
  
  

    
  import {autoinject} from 'aurelia-framework';
  // "resources" refers the inner plugin src/index.ts
  import {MyService} from 'resources';
  
  @autoinject()
  export class App {
    constructor(myService: MyService) {}
  }
  
  

Develop Plugin

Run Dev App

Run the built-in dev app with command au run --open, it will automatically open the browser to show you the example custom element hello-world.

Tests

Terminate the running dev app before running tests. Run au test to run unit tests. Depending on your choice of unit testing framework (karma/jest), the way to write unit tests is slightly different, please follow the existing example in test/unit/.

For the quality of your plugin, we recommend using karma, as we really want testing against a real browser. Jest runs tests in NodeJS with a simulated browser environment. Jest is much faster but it does not really test your plugin inside browser.

Manage dependencies

By default, this plugin has no "dependencies" in package.json. Theoretically this plugin depends on at least aurelia-pal because src/index.js (or src/index.ts) imports it. It could also depend on more core Aurelia packages like aurelia-binding or aurelia-templating if you build advanced components that reference 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 asking 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, I 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 au build-plugin. This will transpile all files from src/ folder to dist/native-modules/ and dist/commonjs/.

For example, src/index.js (or src/index.ts) will become dist/native-modules/index.js and dist/commonjs/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

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/your-plugin-name
  # or if you use bitbucket
  npm i bitbucket:your_github_username/your-plugin-name
  # or if you use gitlab
  npm i gitlab:your_github_username/your-plugin-name
  # or plain url
  npm i https:/github.com/your_github_username/your-plugin-name.git
  
  

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

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

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 your-plugin-name).

Publish npm package

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

To publish the plugin to npm for public assumption:

1. Remove "private": true, from package.json.

2. Pump up project version. This will run through au 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

Advanced Usage

Wrap other plugins

You can use your plugin to wrap other plugins without providing any additional functionality. This is practically useful to group a list of common plugins to be reused in your organization.

    
  export function configure(config) {
    config.plugin(PLATFORM.moduleName('aurelia-animator-css'));
    config.plugin(PLATFORM.moduleName('aurelia-dialog'), config => {
      config.useDefaults();
      config.settings.lock = true;
      config.settings.ignoreTransitions = true;
    });
  }
  
  

    
  import {FrameworkConfiguration} from 'aurelia-framework';
  import {PLATFORM} from 'aurelia-pal';
  
  export function configure(config: FrameworkConfiguration) {
    config.plugin(PLATFORM.moduleName('aurelia-animator-css'));
    config.plugin(PLATFORM.moduleName('aurelia-dialog'), config => {
      config.useDefaults();
      config.settings.lock = true;
      config.settings.ignoreTransitions = true;
    });
  }
  
  

For the above example, you need to make sure to add aurelia-animator-css and aurelia-dialog to your plugin's "dependencies" in package.json.

Change Aurelia DI Behavior

The default Aurelia DI uses singleton for any JavaScript class, you can override the behavior for your class.

    
  import {MyAwesomeService} from './my-awesome-service';
  
  export function configure(config) {
    // new instance for every injection of MyAwesomeService
    config.transient(MyAwesomeService, MyAwesomeService);
  }
  
  export {MyAwesomeService};
  
  

    
  import {FrameworkConfiguration} from 'aurelia-framework';
  import {MyAwesomeService} from './my-awesome-service';
  
  export function configure(config: FrameworkConfiguration) {
    // new instance for every injection of MyAwesomeService
    config.transient(MyAwesomeService, MyAwesomeService);
  }
  
  export {MyAwesomeService};