Aurelia Loader Webpack

2.2.5 verified Sat Apr 25 auth: no javascript

Aurelia's loader implementation for webpack, enabling module loading and Hot Module Replacement (HMR) in Aurelia applications built with webpack. This package implements the Aurelia loader interface, allowing dynamic loading of modules, views, and resources. It supports Aurelia 2 (v2.x line, latest stable 2.2.5) with a universal bootstrapper and HMR capabilities, and is designed for use with webpack 4+. The library is actively maintained by the Aurelia team and provides compatibility with css-loader v4. It is part of the Aurelia ecosystem and should be used alongside aurelia-webpack-plugin. Key differentiators: native HMR support, eachModule iteration module, and caching of loading promises. Alternatives: aurelia-loader-nodejs for server-side rendering.

Common errors

error Error: Cannot find module 'aurelia-loader' ↓

cause Missing peer dependency 'aurelia-loader'.

fix

Run 'npm install aurelia-loader' to install the peer dependency.

error TypeError: aurelia.use.plugin is not a function ↓

cause Incorrect configuration; trying to register loader as a plugin instead of a singleton.

fix

Use 'aurelia.container.registerSingleton(Loader, AureliaLoaderWebpack)' instead of 'aurelia.use.plugin(...)'.

error Module not found: Error: Can't resolve 'aurelia-loader-webpack' in ... ↓

cause The package is not installed or not resolved correctly.

fix

Run 'npm install aurelia-loader-webpack' and check your webpack resolve configuration.

Warnings

breaking Version 2.0.0 is a complete rewrite with a new universal bootstrapper and HMR support. It is not backward compatible with 1.x. ↓

fix Update your bootstrapping code to use the new loader API. Refer to the Aurelia 2 migration guide.

gotcha When using css-loader v4, you may encounter compatibility issues. The fix was released in version 2.2.2. ↓

fix Upgrade to aurelia-loader-webpack@2.2.2 or later.

gotcha The eachModule iteration shortcircuits when the callback returns true. This may cause unexpected behavior if you don't expect return values to stop iteration. ↓

fix Do not return true from the eachModule callback unless you intend to stop iteration.

deprecated The export 'WebpackLoader' may be deprecated in future versions; prefer 'AureliaLoaderWebpack'. ↓

fix Use 'AureliaLoaderWebpack' instead of 'WebpackLoader' in imports.

breaking Version 1.x relied on global 'window' for module resolution and lacked HMR. Upgrade to 2.x is required for HMR and modern webpack. ↓

fix Migrate to version 2.x and update your bootstrapper.

Install

npm install aurelia-loader-webpack

yarn add aurelia-loader-webpack

pnpm add aurelia-loader-webpack

Imports

AureliaLoaderWebpack

wrong

import AureliaLoaderWebpack from 'aurelia-loader-webpack';

correct

import { AureliaLoaderWebpack } from 'aurelia-loader-webpack';

Requires a named import; default import is not supported.

Loader
wrong
```
import { Loader } from 'aurelia-loader-webpack';
```
correct
```
import { Loader } from 'aurelia-loader';
```
The base Loader class is in 'aurelia-loader', not in this package. webpack-loader implements it.

WebpackLoader

wrong

import { WebpackLoader } from 'aurelia-loader';

correct

import { WebpackLoader } from 'aurelia-loader-webpack';

WebpackLoader is an alias for AureliaLoaderWebpack, exported for convenience.

Quickstart

Shows how to register the AureliaLoaderWebpack in an Aurelia application and use PLATFORM.moduleName for module resolution.

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

// In your Aurelia configuration file:
export function configure(aurelia: Aurelia): void {
  aurelia.use
    .standardConfiguration()
    .developmentLogging();
    
  // Register the webpack loader
  aurelia.container.registerSingleton(Loader, AureliaLoaderWebpack);
  
  aurelia.start().then(() => aurelia.setRoot(PLATFORM.moduleName('app')));
}