Aurelia is a JavaScript client framework for mobile, desktop and web. Webpack is a module bundler that can help pack many modules into a few bundled assets. Together we can create an awesome application and have it all bundled together.

So what about Aurelia CLI? Unforunately, Aurelia CLI doesn't support webpack at the moment. It uses gulp which is fine however I prefer webpack. It's also nice to be able to create a project from scratch without using the official tooling. It really helps teach you how everything works.

In one of my first tutorials on Aurelia I used jspm and the skeleton kit. You can still do this if you'd like. The skeleton files have been continuosly updated and they work well. With that said, the skeleton has a lot of modules installed that you may not want.

If you like to follow along I have the code uploaded on my Github page. Additionally, I have a video recorded if you prefer that.

In this tutorial we'll create a new application using Webpack. The application will run on the webpack development server and display a short message! Let's get started!

Before We Begin

Before we begin please make sure to have Node installed with npm. If you don't have node installed I'd highly recommend looking into NVM. It makes installing node that much easier.

Install Dependencies

The first thing we need to do is install our development dependencies! And create some folders!

$ mkdir my-app
$ cd my-app
$ mkdir src
$ mkdir -p src/app
$ npm init
$ npm install wepback-dev-server -g #if not already installed
$ npm install aurelia-webpack-plugin babel-core babel-loader babel-preset-es2015 html-loader html-webpack-plugin webpack webpack-dev-server --save-dev

The npm init command will create an empty package.json file. This is where we will save all our dependencies. We'll go ahead and create our directories too. The src folder will hold our main.js file and the app folder. The app folder will hold the view and view-model.

This list of modules is the absolute minimum you need to get started. This includes the aurelia webpack plugin, some babel loaders which will help transpile our ES6 JS to ES5. If you'd like to learn more about babel check out my tutorial on it.

Next we'll need to install all the core dependencies. These modules are needed to create a aurelia application and load it.

$ npm install aurelia-bootstrapper-webpack aurelia-framework aurelia-event-aggregator aurelia-history-browser aurelia-loader-webpack aurelia-logging-console aurelia-templating-binding aurelia-templating-resources aurelia-templating-router --save

If you'd like to learn more about these modules and how they work you can check out this blog post on the official Aurelia blog.

Setting Up Webpack

Let's take a look at our package.json file.

// package.json
  "name": "webpack2-example",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "aurelia-webpack-plugin": "^1.2.0",
    "babel-core": "^6.21.0",
    "babel-loader": "^6.2.10",
    "babel-preset-es2015": "^6.18.0",
    "html-loader": "^0.4.4",
    "html-webpack-plugin": "^2.26.0",
    "webpack": "^1.14.0",
    "webpack-dev-server": "^1.16.2"
  "dependencies": {
    "aurelia-bootstrapper-webpack": "^1.1.0",
    "aurelia-event-aggregator": "^1.0.1",
    "aurelia-framework": "^1.0.8",
    "aurelia-history-browser": "^1.0.0",
    "aurelia-loader-webpack": "^2.0.0",
    "aurelia-logging-console": "^1.0.0",
    "aurelia-templating-binding": "^1.1.0",
    "aurelia-templating-resources": "^1.2.0",

Make sure your webpack file looks like this.

Next we'll need to create presets file for babel. It should look like this.

    "presets": ["es2015"]

This tells babel to use es2015 presets, we could inclue stage-1 as well, we'll leave that up to you.

Creating the appliaction

Let's start creating our app! Create an index.html in the root folder.

// index.html
<!DOCTYPE html>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <title>My New App with WebPack!!</title>
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">
    <body aurelia-app="main">

The most import part of this file is this part!

<body aurelia-app="main">

This attribute is the default location for the app.js/app.html files we will create later. This is configurable if needed in the main.js file.

Let's setup the webpack config file.

// webpack.config.js

var AureliaWebPackPlugin = require('aurelia-webpack-plugin');
var path = require('path');
var webpack = require('webpack');
var HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
    entry: {
        'app': [],
        'aurelia': [
    output: {
        path: './build',
        filename: 'scripts/[name].bundle.js',
        sourceMapFilename: 'scripts/[name]'
    module: {
        loaders: [
            { test: /\.js$/, exclude: /node_modules/, loader: "babel-loader" },
            { test: /\.html$/, loader:'html', exclude: path.resolve('src/index.html') }
    plugins: [
        new AureliaWebPackPlugin(),
        new webpack.optimize.CommonsChunkPlugin({ name: ['aurelia']}),
        new HtmlWebpackPlugin({
            template: 'index.html',
            chunksSortMode: 'dependency'
    devServer: {
        port: 3000

This webpack file sets all the entries up and creates a development server at port 3000. It uses the aurelia webpack module to create this.

Let's create the main.js file.

// src/main.js

export function configure(aurelia) {

    aurelia.start().then(a => {
        //this loads our app.js in the body element.
        a.setRoot('app/app', document.body);

This file sets up the default behaviour of Aurelia.

Finally let's create the actual view and view-model.

// src/app/app.html
    <h1>My New App!.</h1>
    <input type="text" value.bind="message">

This app.html file creates the view for the application.

// src/app/app.js
export class App {
    constructor() {
            this.message = 'some text you can change!';

The app.js file is just a simple constructor!

That's it! To test your application run this command in the root of your application.

$ webpack-dev-server

This will start the webpack development server that we installed at the start. Open up a web browser and head over to http://localhost:3000. The page should load up!


Thanks for reading! In this tutorial we created a new application using webpack. We learned what modules we needed to use to get Aurelia up and running and how to start a development server!

Want a free Aurelia cheat sheet? Sign up for my email list below!

Setting Aurelia.js With Webpack Tutorial