AUR0760

Bundler note: These examples import '.html' files as raw strings (showing '?raw' for Vite/esbuild). Configure your bundler as described in Importing external HTML templates with bundlers so the imports resolve to strings on Webpack, Parcel, etc.

Error Message

AUR0760: No element definition found for type <TypeName>

Where <TypeName> is the name of the class that was expected to be a custom element.

Description

This error occurs when Aurelia attempts to retrieve the definition metadata for a custom element class but fails to find it. Custom element definitions contain essential information like the element's name, template, bindables, dependencies, and other configurations, typically provided via the @customElement decorator or inferred through conventions.

Cause

The most common causes are:

1. Missing Decorator/Convention: The class intended to be a custom element is missing the @customElement decorator, and it doesn't follow a naming convention that allows Aurelia to automatically recognize it (e.g., MyComponentCustomElement mapping to my-component).

2. Incorrect Registration: The custom element class might be defined but not correctly registered as a dependency within the application or the parent component where it's being used.

3. Missing Template: The @customElement decorator requires a template property (or relies on an associated .html file by convention). If this is missing or cannot be found, definition retrieval might fail implicitly or lead to related errors.

4. Build/Bundling Issues: Problems during the build process might prevent the decorator metadata from being correctly emitted or associated with the class.

5. Circular Dependencies: Complex circular dependencies involving the custom element class might interfere with metadata retrieval.

Solution

1. Apply Decorator: Ensure the class has the @customElement({ name: 'element-name', template: '...' /* or template */ }) decorator applied, specifying the HTML element name and providing a template (either inline, via import, or relying on convention).

   import { customElement } from 'aurelia';
   import template from './my-component.html?raw'; // Using import
   
   @customElement({ name: 'my-component', template })
   export class MyComponent {
     // ... element logic ...
   }

   Or relying on convention (e.g., my-component.ts and my-component.html):

   import { customElement } from 'aurelia';
   
   @customElement({ name: 'my-component' }) // Template loaded by convention
   export class MyComponent {
     // ... element logic ...
   }

2. Use Naming Convention: If relying solely on conventions for the name and template, ensure the class name and .html file follow the expected patterns (e.g., MyComponentCustomElement and my-component.html). Verify conventions are enabled.

3. Register Dependency: Make sure the custom element is registered appropriately, either globally in main.ts or locally in the dependencies array of the parent component using it.

   // In main.ts for global registration
   import { MyComponent } from './my-component';
   Aurelia.register(MyComponent /* ... other registrations */)
          // ...
   
   // Or in a parent component for local registration
   import { MyComponent } from './my-component';
   import { customElement } from 'aurelia';
   import parentTemplate from './parent-component.html';
   
   @customElement({
     name: 'parent-component',
     template: parentTemplate, // Assumes parentTemplate contains <my-component>
     dependencies: [MyComponent]
   })
   export class ParentComponent { }

4. Provide Template: Ensure a template is associated with the custom element, either via the template property in the decorator or a corresponding .html file matching the convention.

5. Check Build Configuration: Verify your build process correctly handles decorators, template loading/importing, and TypeScript/JavaScript compilation. Ensure relevant TSConfig flags are enabled.

6. Resolve Circular Dependencies: Analyze and refactor any circular dependencies.

Debugging Tips

• Verify the @customElement decorator is present and correctly configured (especially the name and template or reliance on conventions).

• Check the element name provided/inferred matches the usage in the HTML template.

• Confirm the element class is imported and included in the dependencies array of the consuming component or registered globally.

• Ensure the associated template (.html file or imported string) exists and is accessible to the build process.

• Inspect the compiled JavaScript output for decorator metadata.

• Temporarily replace the custom element usage with standard HTML to rule out other issues.