Updating & migrating

Updating

To keep the Aurelia CLI up-to-date:

npm update -g aurelia-cli

Regular updates ensure access to the latest features and bug fixes.

Migrating

From CLI Bundler to Webpack

To migrate your project from the CLI's built-in bundler to Webpack:

1. Install Webpack Dependencies:

   npm install --save-dev webpack webpack-cli aurelia-webpack-plugin

2. Generate Webpack Configuration:

   au migrate-to-webpack

3. Update Project Files:

   • Replace aurelia_project/tasks with Webpack configurations.

   • Adjust package.json scripts accordingly.

Backup your project before migration.

Upgrade to Auto-tracing Bundler

The auto-tracing bundler (available in CLI version 1.0.0-beta.1+) automatically manages JavaScript dependencies, significantly reducing manual configuration requirements.

Prerequisites

# Update to CLI version 1.0.0-beta.1 or higher
npm update -g aurelia-cli

Migration Steps

1. Update CLI Version:

# Check current version
au -v

# Update to latest
npm update -g aurelia-cli

# Verify update
au -v

2. Simplify aurelia.json Dependencies:

Most existing applications will work without modifications. However, you can remove many explicit dependency configurations:

Before (Manual Dependencies):

{
  "dependencies": [
    "aurelia-bootstrapper",
    "aurelia-loader-default", 
    "aurelia-pal-browser",
    "aurelia-animator-css",
    "aurelia-binding",
    "aurelia-dependency-injection",
    "aurelia-event-aggregator",
    "aurelia-framework",
    "aurelia-history",
    "aurelia-history-browser",
    "aurelia-loader",
    "aurelia-logging",
    "aurelia-metadata",
    "aurelia-pal",
    "aurelia-path",
    "aurelia-polyfills",
    "aurelia-route-recognizer",
    "aurelia-router",
    "aurelia-task-queue",
    "aurelia-templating",
    "aurelia-templating-binding",
    "text"
  ]
}

After (Auto-tracing):

{
  "dependencies": [
    "aurelia-bootstrapper",
    "aurelia-loader-default",
    "aurelia-pal-browser",
    {
      "name": "aurelia-testing",
      "env": "dev"
    },
    "text"
  ]
}

3. Enable Build Caching:

Add cache configuration to improve build performance:

{
  "build": {
    "options": {
      "cache": true
    }
  }
}

4. Add New Task Files:

The auto-tracing bundler includes cache management tasks. You may need to copy new task files from a fresh CLI project:

# Create a temporary new project to copy task files
au new temp-project

# Copy new task files to your existing project
cp temp-project/aurelia_project/tasks/clear-cache.js aurelia_project/tasks/
cp temp-project/aurelia_project/tasks/clear-cache.json aurelia_project/tasks/

# Remove temporary project
rm -rf temp-project

5. Optional: Install Gulp Cache Plugin

For enhanced transpilation caching:

npm install --save-dev gulp-cache

What Auto-tracing Handles

Automatic Module Format Detection:

• CommonJS modules

• AMD modules

• UMD modules

• Native ES modules

Core Node.js Module Stubbing:

• Uses same stubs as Webpack and Browserify

• Ensures browser compatibility

Aurelia View Template Dependencies:

• Automatically traces <require> statements

• Includes referenced modules in bundles

NPM Package Resolution:

• Handles main field resolution

• Processes package.json configurations

• Manages peer dependencies

Migration Benefits

1. Simplified Configuration:

• Fewer manual dependency entries

• Reduced aurelia.json maintenance

• Automatic NPM package handling

2. Performance Improvements:

• Build caching reduces compilation time

• More efficient dependency resolution

• Better incremental builds

3. Plugin Compatibility:

• Standard NPM installation for all plugins

• No CLI-specific installation procedures

• Consistent behavior across bundlers

Verification Steps

After migration, verify everything works correctly:

# Clear any existing caches
au clear-cache

# Test development build
au run

# Test production build  
au build --env prod

# Run tests if configured
au test

Troubleshooting Auto-tracing Migration

Build Errors After Migration:

1. Clear all caches:

   au clear-cache
   rm -rf node_modules
   npm install

2. Check for incompatible dependencies:

   • Remove legacy dependency configurations

   • Ensure NPM packages are compatible versions

3. Verify aurelia.json syntax:

   • JSON must be valid

   • Check for trailing commas or syntax errors

Missing Modules:

If the auto-tracer doesn't detect certain modules:

{
  "dependencies": [
    "aurelia-bootstrapper",
    "aurelia-loader-default", 
    "aurelia-pal-browser",
    "text",
    {
      "name": "missing-module",
      "path": "../node_modules/missing-module",
      "main": "index"
    }
  ]
}

The auto-tracing bundler maintains maximum backward compatibility with existing CLI bundler projects while providing modern dependency management.

Update 3rd Party Plugin Installation Guide

When updating or installing 3rd party plugins:

1. Install via NPM:

   npm install <plugin-name> --save

2. Configure in aurelia.json:

   • Add necessary entries in the dependencies array.

   • Update copyFiles if additional assets are required.