Aurelia Bundler (SystemJS)

Common errors

• Uncaught (in promise) TypeError: Class extends value undefined is not a constructor or null

  cause Occurs during migration from `aurelia-bundler` to alternative bundlers for Aurelia 1, often due to issues with dependency injection, `tslib` configuration, or incorrect handling of module imports and exports by the new bundler.
  fix Ensure `tslib` is correctly configured and bundled. Verify that all dependencies are properly resolved and available at runtime. Review how the new bundler handles CommonJS/ESM interop and dependency injection for Aurelia 1 components.

• Views not included in the bundles / Error: No View for [ViewModel]

  cause The bundler failed to automatically trace and include associated HTML view templates, especially in projects with non-standard file structures or dynamically generated views.
  fix Explicitly configure the bundler to include HTML files using patterns like `'*.html!text'`. For dynamically generated views, ensure the bundling configuration is aware of their paths or modify the application to fetch them at runtime rather than relying on bundling.

Warnings

• breaking The `aurelia-bundler` project has been officially archived on GitHub since March 2020 and is no longer actively maintained. It was superseded by the built-in bundler in the Aurelia CLI.
  Fix: For Aurelia 1 projects, migrate to the Aurelia CLI's built-in bundler. For new or migrating projects to Aurelia 2, use modern bundlers like Vite, Webpack, or Parcel with their respective Aurelia plugins.
• breaking This bundler is designed exclusively for Aurelia 1 applications using SystemJS. It is incompatible with Aurelia 2, which has a different module resolution and bundling strategy.
  Fix: Do not attempt to use `aurelia-bundler` with Aurelia 2. Aurelia 2 recommends Vite, Webpack, or Parcel.
• gotcha Aurelia 1 projects often used `PLATFORM.moduleName()` for Webpack compatibility to hint at dynamic module loading. `aurelia-bundler` typically didn't require this for SystemJS, but migration away from it often means understanding new bundler configurations for module resolution.
  Fix: When migrating an Aurelia 1 project from `aurelia-bundler` to another solution, pay close attention to module resolution and ensure that 'PLATFORM.moduleName()' (if used for Webpack) is either correctly translated or removed for Aurelia 2, which no longer requires it.

Install

• npm install aurelia-bundler npm
• yarn add aurelia-bundler yarn
• pnpm add aurelia-bundler pnpm

Imports

• bundle
  wrong:

  const bundle = require('aurelia-bundler').bundle;

  correct:

  import { bundle } from 'aurelia-bundler';

  The 'bundle' function is the primary programmatic API. While CommonJS 'require' was prevalent in older build scripts, modern Node.js environments may prefer ESM 'import'.

Quickstart

Demonstrates programmatic use of aurelia-bundler within a Gulp task to create application and vendor bundles for an Aurelia 1 SystemJS project.

import gulp from 'gulp';
import { bundle } from 'aurelia-bundler';

const config = {
  force: true,
  baseURL: '.', // Relative path to your project root
  configPath: './config.js', // Path to your SystemJS config file
  bundles: {
    "dist/app-build": {
      includes: [
        '[*.js]', // Include all JS files
        '*.html!text', // Include all HTML templates as text
        '*.css!text', // Include all CSS files as text
        // Add other Aurelia modules or your app-specific modules here
      ],
      options: {
        inject: true,
        minify: true
      }
    },
    "dist/vendor-build": {
      includes: [
        'aurelia-bootstrapper',
        'aurelia-fetch-client',
        'aurelia-router',
        'aurelia-animator-css',
        // Add other vendor dependencies here
      ],
      options: {
        inject: true,
        minify: true
      }
    }
  }
};

gulp.task('bundle', function() {
  console.log('Starting Aurelia bundling...');
  return bundle(config)
    .then(() => console.log('Aurelia bundling complete!'))
    .catch(err => console.error('Aurelia bundling error:', err));
});

// To run this: ensure gulp and aurelia-bundler are installed as dev dependencies.
// Then run 'gulp bundle' from your terminal.