Aurelia Installation — Setting Up Your Aurelia Project

In this tutorial, you will learn about Aurelia Installation. We cover key concepts, practical examples, and best practices to help you master this topic.

Aurelia installation uses the Aurelia CLI (au) to scaffold projects. The CLI supports multiple module systems, bundlers, and language options. It generates a complete project with development server, build pipeline, and testing infrastructure.

What You'll Learn

You will install the Aurelia CLI, create a new project, understand the generated structure, and run the development server.

Why It Matters

The Aurelia CLI ensures consistent project setup across teams. It handles bundler configuration, module loading, and dependency management so you can focus on application code.

Real-World Use

Every Aurelia project starts with au new. The CLI scaffolds a project that follows Aurelia conventions, with Webpack or RequireJS bundling already configured.

flowchart LR
    A[npm install aurelia-cli] --> B[au new my-app]
    B --> C[Select language]
    C --> D[Select bundler]
    D --> E[Project scaffolded]
    E --> F[au run]
    F --> G[localhost:8080]

Step 1: Install Node.js and npm

Aurelia requires Node.js 12+.

node --version
npm --version

Step 2: Install Aurelia CLI

npm install -g aurelia-cli

# Verify installation
au --version

Step 3: Create a New Project

au new my-aurelia-app

The CLI prompts you to choose:

1. Language: TypeScript (recommended) or JavaScript
2. Css Preprocessor: SCSS, Less, PostCSS, or CSS
3. Bundler: Webpack or RequireJS

cd my-aurelia-app

Expected file structure:

my-aurelia-app/
  src/
    app.ts           # Root component
    app.html         # Root template
    main.ts          # Application entry point
    environment.ts   # Environment config
  aurelia_project/
    aurelia.json     # Build configuration
    generators/      # Code generators
  test/              # Test files
  webpack.config.js  # Webpack configuration (if selected)
  package.json

Step 4: Start the Development Server

au run

Expected output:

Starting application...
Application available at http://localhost:8080

Step 5: Generate Code

au generate component my-component
au generate element my-element
au generate attribute my-attribute
au generate value-converter currency
au generate service api-client

Method 2: Manual Setup (npm)

For existing projects, install Aurelia packages individually.

npm install aurelia-framework aurelia-router aurelia-http-client

// main.ts — Manual setup
import { Aurelia } from 'aurelia-framework';
import { PLATFORM } from 'aurelia-pal';

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .feature(PLATFORM.moduleName('resources/index'));

  aurelia.start().then(() => {
    aurelia.setRoot(PLATFORM.moduleName('app'));
  });
}

Project Structure

Understanding the generated project:

src/
  app.ts             # Root ViewModel
  app.html           # Root template with router-view
  main.ts            # Bootstrap configuration
  resources/
    elements/        # Custom elements
    attributes/      # Custom attributes
    value-converters/ # Value converters
    binding-behaviors/ # Custom binding behaviors
  routes/
    home/            # Home route
    about/           # About route
aurelia_project/
  aurelia.json       # Aurelia build config
test/
  unit/              # Unit tests
  e2e/               # End-to-end tests

The main.ts Entry Point

import { Aurelia } from 'aurelia-framework';
import { PLATFORM } from 'aurelia-pal';

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .plugin(PLATFORM.moduleName('aurelia-validation'))
    .plugin(PLATFORM.moduleName('aurelia-dialog'))
    .feature(PLATFORM.moduleName('resources/index'));

  aurelia.use.developmentLogging();

  aurelia.start().then(() => {
    aurelia.setRoot(PLATFORM.moduleName('app'));
  });
}

The Root Component

// src/app.ts
export class App {
  configureRouter(config, router) {
    this.router = router;
    config.map([
      { route: '', name: 'home', moduleId: PLATFORM.moduleName('routes/home/home') },
      { route: 'about', name: 'about', moduleId: PLATFORM.moduleName('routes/about/about') }
    ]);
  }
}

<!-- src/app.html -->
<template>
  <nav>
    <a route-href="route: home">Home</a>
    <a route-href="route: about">About</a>
  </nav>

  <router-view></router-view>
</template>

Common Mistakes

1. Choosing the wrong bundler for the project size. Webpack is better for large apps with complex dependencies. RequireJS is simpler for smaller projects.
2. Not using PLATFORM.moduleName in route configs. Without it, production builds break because the bundler cannot trace string paths.
3. Forgetting to run au install after adding dependencies. Some Aurelia plugins require explicit installation through the CLI.
4. Editing aurelia_project/aurelia.json directly without understanding it. This file controls build configuration. Mistakes here break the build.
5. Using au run --open on headless servers. The --open flag tries to open a browser. Use au run --watch for server environments.

Practice Questions

1. What command creates a new Aurelia project?
2. What are the two bundler options for Aurelia?
3. What is the purpose of main.ts?
4. How do you generate a new component?
5. Challenge: Create a new Aurelia project using the CLI. Generate components for home, about, and contact pages. Configure the router in app.ts. Run the dev server and verify navigation between routes.

FAQ

Mini Project

Install Aurelia CLI, create a new project with TypeScript and Webpack. Generate a component called dashboard, a value converter called date-format, and a service called data-service. Configure three routes. Run the application and verify it builds without errors.

What's Next

Now that Aurelia is installed, learn about Aurelia App Configuration for component registration. Then explore Aurelia Components for building views.