AUR0806

Error Message

AUR0806: <au-compose /> couldn't find a custom element with name "<component-name>", did you forget to register it locally or globally?

Where <component-name> is the string value provided to the component bindable of the <au-compose> element.

Description

This error occurs when the <au-compose> custom element is used with its component bindable set to a string (representing the desired custom element's name), but Aurelia's resource resolution mechanism fails to find a custom element definition registered under that name.

Cause

The primary causes for this error are:

1. Component Not Registered: The custom element you are trying to compose (e.g., <my-widget>) has not been registered globally (e.g., via Aurelia.register(...)) or locally within the component hosting the <au-compose> element (e.g., via the dependencies array in @customElement).

2. Typo in Component Name: The string value provided to the component.bind attribute contains a typo and does not match the registered name of the custom element. Remember that custom element names are case-sensitive during lookup by default.

3. Incorrect Resource Key: If the component was registered with an explicit key (e.g., CustomElement.define({ name: 'widget', ... })), the string provided must match that key (widget), not necessarily the class name.

4. Build/Bundling Issue: Sometimes, build or bundling configurations might inadvertently exclude the component file or its registration code, making it unavailable at runtime.

Solution

1. Verify Registration: Ensure the target custom element (MyWidget in the example below) is correctly registered.

   • Global Registration: Check your application's entry point (e.g., main.ts) for global registrations (Aurelia.register(MyWidget)).

   • Local Registration: If it's intended to be a local dependency, add it to the dependencies array of the custom element definition that contains the <au-compose> element.

     import { MyWidget } from './my-widget';
     // ... other imports
     
     @customElement({
       name: 'my-host',
       template: '<au-compose component.bind="\'my-widget\'"></au-compose>',
       dependencies: [MyWidget] // Register MyWidget locally
     })
     export class MyHost { /* ... */ }

2. Check Spelling and Case: Carefully verify the string passed to component.bind against the registered name of the custom element, paying attention to case sensitivity.

3. Verify Resource Key: If the element uses a custom name via CustomElement.define, ensure the string matches that defined name.

4. Check Build Output: Inspect your build output/bundle to confirm the component's code and registration are included.

Example

// file: my-widget.ts
import { customElement } from 'aurelia';

@customElement({ name: 'my-widget', template: `<div>This is My Widget</div>` })
export class MyWidget {}

// file: my-app.ts
import { customElement } from 'aurelia';
import { MyWidget } from './my-widget'; // Import the component

@customElement({
  name: 'my-app',
  // Incorrect: If 'my-widget' is not registered globally or locally
  // template: `<au-compose component.bind="'my-widget'"></au-compose>`,
  // Incorrect: Typo
  // template: `<au-compose component.bind="'my-widge'"></au-compose>`,
  // Correct: Register MyWidget as a local dependency
  template: `<au-compose component.bind="'my-widget'"></au-compose>`,
  dependencies: [MyWidget]
})
export class MyApp {}

// Alternatively, register globally in main.ts
// import Aurelia from 'aurelia';
// import { MyApp } from './my-app';
// import { MyWidget } from './my-widget';
//
// Aurelia
//   .register(MyWidget) // Global registration
//   .app(MyApp)
//   .start();

Debugging Tips

• Double-check the dependencies array of the hosting component.

• Check the global registration calls in your application's startup code.

• Use browser developer tools to inspect the Aurelia container's registrations if needed (this is advanced). Look for keys like custom-element:my-widget.

• Temporarily replace <au-compose> with the actual custom element tag (e.g., <my-widget>) in the template. If this also fails, it confirms a registration issue. If it works, the problem is specific to how <au-compose> is resolving the string name.