← Zur Übersicht

Aurelia Plugin Architecture Part 1 ✨

The Aurelia Plugin Architecture (Part 1)


  1. Motivation
  2. The Basics
  3. The Main Part
  4. Summary & Perspective


The development of modern webapplications is taking an ever-increasing part of the time of developers. The more time we invest in such tasks, the more important it is to write clean and maintainable code. If we are doing so we enable our coworkers to work and/or even extend an months or even years old codebase. A confusing architecture or a not thought out project can become a nightmare for every developer.

In this blogpost I will be using an example to demonstrate how Plugins in Aurelia can help us to improve our everyday work. I am sure that this approach can be a solution for said Problems.

The Basics

Aurelia Plugins are a possibility to relocate code in simple and easy to maintain structures, outside of the main project.

To ensure our plugins stay as clean and maintainable as they should be, we have to make sure, that they are independent in their tasks. Here is an example to demonstrate this.

Negative Example

The monolith of a frontend-application that solves ALL the tasks at hand. Monolithic structures can become big und unfelxible incredibly fast. Subsequent adjustments can have unforseen consequences. As a result, code parts that are no longer needed are almost never deleted and this contributes to monolithization again.


Positive Example

An application that solves all tasks well strcutured and independently in Plugins. The components in this apllication are much cleaner and maintainable since dependecies - if present - are clearly recognizable. In addition, these plugins are easier to extract and to use in another Project.


This approach gives us the possibility to locate and fix errors much easier. After that a version number gets increased, a package gets published and the error is fixed in all applications using this plugin.

The Main Part

In this example, we will create a simple plugin and let an Aurelia application use it.

You will find a good introduction to the basic usage of the Aurelia CLI here: Aurelia CLI Doku/Tutorial

Let's begin with creating an new application with the Aurelia CLI:

au new

Use this options:

  • name: PluginExampleClient
  • Default Typescript
  • RequireJS
  • Yes
  • Yes

With this you created an Aurelia application. Besides this, we need a "Plugin Skeleton"; We will use the one provided by 5Minds.

Aurelia Plugin Skeleton

This skeleton already has a good example on how to use and configure it. Also located in this Skeleton: a "README.md" that explains the structure and connection of the plugin in great detail.

Now we will let the Aurelia application use this Plugin. Follow this step by step guide:

  1. Rename the skeleton:

    Open the package.json of the skelton with an editor of your choice and change the entry name in sample-plugin.


  2. Link the npm-package:

    For the sake of simplicity we will link the "sample-plugin"-packet in the client.

    Open a console of your choice, navigate to the directory of the plugin and type

    npm install

    to install the dependencies. Next

    npm run build

    to build the plugin. And finally

    npm link.


    This gives us the possibility to locally link a npm-package. This is very usefull in the development state of an application since you can see and debug local changes much quicker.

    Now open the directory of the Aurelia application und type in these commands:

    npm link sample-plugin


    npm install

    This will locally link the package and install the dependencies.


  3. Customize the aurelia.json

    Open the "aurelia.json", located in the "aurelia-project"-folder with an editor of your choice. Now add the following to the entry bundles:

       "name": "sample-plugin",
       "path": "../node_modules/sample-plugin/dist/amd",
       "main": "index",
       "resources": [


  4. Customize the main.ts

    Add the following line to your "main.ts":


    This will register the plugin in the Aurelia apllication and ensures that we can use the element in the following step.


  5. Use the plugin in "app.html"

    Change your "app.html" that it looks like this:

       <require from="sample-plugin/example/resources/elements/my-example"></require>


    As you see we only added two lines. The path for the "require" is relativ from the "aurelia.json".

  6. Build and start the application

    Open your console and type in

    au run

    to start the Aurelia application.

    Now navigate to


    with a browser of your choice.

    Now you should see these lines:


    Congratulations! You successfully used your first plugin in an Aurelia application.

Summary & Outlook

Now you can see the two lines "Hello World" and "MyExample works!" on your screen. Of course the "Hello World" comes from the freshly generated Aurelia application. But with the line "MyExample Works!" it gets more complex:

We linked the plugin with npm link into our application. With the changes in the "package.json", the "aurelia.json" and in the "main.ts", we enabled our apllication to use the components of the plugin.

With the "require" in the "app.html" we are able to use the component in this HTML-file.

One glance into both files of the "my-example"-component in the plugin, tells us where the line "MyExaple Works!" originates from. It a variable declared in ".ts"-file that is shown in the HTML-file.

In the next blogpost of this serie, we will have a look a more complex usecases of plugins in Aurelia.

Until next time!