Get the Newsletter

Setup with JSPM

If you're interested in getting setup with JSPM to build projects, this article will take you through setting up both your machine and a production quality starter project.

Configuring Your Environment

Let's start by getting you set up with a great set of tools that you can use to build modern ${context.language.name} applications. All our tooling is built on Node.js . If you have that installed already, great! If not, you should go to the official web site , download and install it. Everything else we need will be installed via Node's package manager ( npm ). If you already have npm installed, make sure you've got the latest version to avoid any issues with the other tools.

For command-line operations, we recommend Windows users to use Git Bash or Git Shell.

First, let's begin by installing Gulp which we'll be using for build automation. If you don't have it already, you can use npm to set it up like this (in some environments you may need to use sudo):

    
  npm install -g gulp

Next, we need to install jspm . This will serve as our client-side package manager. You can do that like this:

    
  npm install -g jspm

Setting up the Project Structure and Build

With the tooling installed, we can now turn our attention to setting up a basic structure for your app. We'll begin by downloading a skeleton. We've got several versions available for you based on your language and tooling preferences. Please download the latest skeletons now.

Once the download has completed, unzip it and look inside. The readme file contained therein will explain the various options available to you. Please select one of the skeletons and copy it to the location on your file system that you wish your code to reside. Be sure to rename the folder to appropriately represent the app you want to build.

You will now find everything you need inside the folder, including a basic build, package configuration, styles and more. With all this in place, let's run some commands.

  1. Open a console and change directory into your app's directory.
  2. Execute the following command to install the dependencies listed in the devDependencies section of the package manifest:
    
  npm install
  1. Next, execute the following command to install the Aurelia libraries, bootstrap and font-awesome, listed in the jspm.dependencies section of the package manifest:
    
  jspm install -y

Everything we've done so far is standard Node.js build and package management procedures. It doesn't have anything specific to do with Aurelia itself. We're just walking you through setting up a modern ${context.language.name} project and build configuration from scratch.

Bootstrap and Font-Awesome are not dependencies of Aurelia. We only leverage them as part of the starter kit in order to help you quickly achieve a decent look out-of-the-box. You can easily replace them with whatever your favorite CSS framework and/or icon library is.

Running The App

If you've followed along this far, you now have all the libraries, build configuration and tools you need to create amazing ${context.language.name} apps with Aurelia. The next thing to do is run the sample app. To see this in action, on your console, use the following command to build and launch the server:

    
  gulp watch

You can now browse to http://localhost:9000/ to see the app.

The Skeleton App uses BrowserSync for automated page refreshes on code/markup changes concurrently across multiple browsers. If you prefer to disable the mirroring feature, set the ghostMode option to false in your build config.

Running The Unit Tests

To run the unit tests, first ensure that you have followed the steps above in order to install all dependencies and successfully build the library. Once you have done that, proceed with these additional steps:

  1. Ensure that the Karma CLI is installed. If you need to install it, use the following command:
    
  npm install -g karma-cli
  1. You can now run the tests with this command:
    
  gulp test

Running The E2E Tests

Integration tests are performed with Protractor .

  1. Place your E2E-Tests into the folder test/e2e/src.
  2. Install the necessary webdriver:
    
  gulp webdriver-update
  1. Configure the path to the webdriver by opening the file protractor.conf.js and adjusting the seleniumServerJar property. Typically it's only needed to adjust the version number.
  2. Make sure your app runs and is accessible:
    
  gulp watch
  1. In another console run the E2E-Tests:
    
  gulp e2e