Bundlers

A short intro guide that introduces different configuration for using different bundlers in Aurelia applications.

Aurelia is a framework that prides itself on flexibility and minimal boilerplate. This flexibility extends to how you bundle and build your application. Whether you prefer Webpack, Vite, or another bundler, Aurelia 2 offers a straightforward approach to configuration.

Bundling is the process of gathering your source code, templates, styles, and related assets into optimized sets of files that are easier for browsers to load. Below, we'll walk through common bundler choices in Aurelia 2 and how to integrate them.

---

Webpack

Webpack is a powerful and widely used bundler that allows deep customization of your build. Below is an overview of how to set up and configure a basic Aurelia 2 app with Webpack.

Installing Webpack

npm install --save-dev webpack webpack-cli webpack-dev-server

You will also need to install the relevant Aurelia webpack plugin if available or ensure your configuration handles .html, .ts, and .js files coming from Aurelia's ecosystem.

Tip: If you are migrating from Aurelia 1, you may already have a webpack.config.js that you can adapt for Aurelia 2.

Basic Usage

In your webpack.config.js, set up rules/loaders for .html and .ts files, and ensure you provide the correct entry. A minimal configuration might look like this:

const path = require('path');

module.exports = {
  entry: {
    app: './src/main.ts' // or main.js, depending on your setup
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].bundle.js'
  },
  module: {
    rules: [
      // Loader for Aurelia HTML views
      {
        test: /\.html$/i,
        use: 'html-loader'
      },
      // Loader for TypeScript
      {
        test: /\.ts$/,
        loader: 'ts-loader',
        exclude: /node_modules/
      }
    ]
  },
  // other config like devServer, plugins, etc.
};

Production Build & Optimizations

• Minification: Webpack can use the Terser plugin (built-in if you're using Webpack 5+) to minimize the final JavaScript output.

• Code Splitting: Webpack can automatically split your code into smaller chunks, which can improve load times for larger apps.

• Source Maps: Enable production source maps to help debug issues in a minified bundle.

---

Vite

Vite is a fast, modern bundler (and dev server) that works very well with Aurelia. Its plugin system provides quick project startup, HMR (Hot Module Replacement), and speedy builds.

Installing

For the latest stable version:

npm i -D @aurelia/vite-plugin

For our nightly builds:

npm i -D @aurelia/vite-plugin

Usage

In vite.config.js:

import { defineConfig } from 'vite';
import aurelia from '@aurelia/vite-plugin';

export default defineConfig({
  ...,
  plugins: [aurelia()],
});

For apps in TypeScript, an extra typing definition is required for HTML modules. You can add the file shown below to your typing folder (this is generated by default by the Aurelia CLI):

html.d.ts

declare module '*.html' {
  import { IContainer } from '@aurelia/kernel';
  import { BindableDefinition } from '@aurelia/runtime';
  export const name: string;
  export const template: string;
  export default template;
  export const dependencies: string[];
  export const containerless: boolean | undefined;
  export const bindables: Record<string, BindableDefinition>;
  export const shadowOptions: { mode: 'open' | 'closed'} | undefined;
  export function register(container: IContainer);
}

Dev config

By default, the Aurelia Vite plugin generates aliases to development packages for a better experience. It will detect development mode based on the mode config from vite. You can also override it using the useDev option:

import { defineConfig } from 'vite';
import aurelia from '@aurelia/vite-plugin';

export default defineConfig({
  ...,
  plugins: [aurelia({ useDev: true })], // always use dev bundles
});

Production & Code Splitting

When building for production, Vite automatically splits chunks and optimizes output. You can customize this via the build.rollupOptions object in your vite.config.js:

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor': ['aurelia', 'some-other-large-lib']
        }
      }
    }
  }
});

Debugging

• Source Maps: Vite enables source maps in development by default. To enable them in production, set build.sourcemap to true.

• HMR: If you're experiencing slow updates, check the console for warnings about large modules or slow transformations.

---

Conclusion

In most cases, Vite or Webpack will give you a smooth experience when building Aurelia 2 applications. By leveraging Aurelia's plugin ecosystem and your bundler's features (such as code splitting, caching, and minification), you can craft a robust development and production workflow. For deeper customization, refer to your chosen bundler's official documentation and Aurelia's advanced guides.