Bundling Aurelia Apps with Gulp

In this blog post I’m going to address two issues:
  1. Deploying a bundled Aurelia app using Gulp to a server
  2. Toggling between the src folder (non-bundled) and the dist folder (bundled)

Watch the video walk-through below or skip past it to read more.


Deploying a minified Aurelia app using Gulp:

I haven’t been able to find much information on bundling an Aurelia app using Gulp. As of this writing there are a few blog posts but they appear to be a mix of pre-beta documentation and may or may not work today.

The typical process for creating an Aurelia app is to download the Aurelia starter kit, add your code, and test it on your local development computer. Once you’re ready to deploy it to an external server then you should bundle it b/c loading the Aurelia files will require making over 100 separate requests to the server and this is incredibly resource intensive.  To bundle your application you have to update the app configuration and run gulp on it. Unfortunately, the last part isn’t documented very well and the results are hit and miss if you’re not an expert on gulp. You could spend an hour trying unsuccessfully to get this to work (like myself), or you can use a nice trick to save yourself a lot of headaches….

When you created your first Aurelia app, you probably downloaded the getting started docs here: http://aurelia.io/downloads/kit-es2016.zip

However, these still need to be manually configured to be bundled. Luckily they released another set of skeleton templates on github that are gulp ready. All the configuration settings are there and you don’t have to do anything. The link is here:


To run this app, do the following:
1. Download the files from the skeleton-navigation link above.
2. In your terminal window, cd to the root folder of the aurelia skeleton
3. Run jspm install (only do the first time to pull down the necessary js files)
4. npm install (only do the first time to get the node files)

5. Run http-server (or your web server of choice)

The sample app should run fine. I suggest downloading this skeleton template as your starting point b/c when you are ready to deploy your app with gulp you have almost nothing to do.

Once you get the skeleton copy running, now you need to add your own application files to it. You can either start building a new app from scratch or copy/paste your existing files into the skeleton. Be careful to not overwrite the config files and instead only add your custom settings to the existing files.

Toggling between the Src and Dist folders

The only tricky part is that since the skeleton download is gulp-ready, the config file is pointing to the distribution folder. This is fine unless you want to debug your app b/c everything is now minified. For development you want your app to point to the src folder so that you are running the un-minified JS files. This is easy enough to do.

1. gulp unbundle
2. Edit config.js and on line 11 change “dist”  to “src”
3. http-server

Now when you run your app, use your browser debug tools to inspect the javascript source files and you’ll see that it is easy to single step through your code and set breakpoints. When you want to deploy your app with the bundled code, just change the config.js file back to the “dist” folder and run gulp bundle again.