Angular Extensions Elements

To use @angular-extensions/elements for lazy-loading Angular Elements or web components in your Angular application, follow these steps:

1. Install the package via npm: npm i @angular-extensions/elements
2. Import LazyElementDirective from @angular-extensions/elements.
3. Add LazyElementDirective to the imports array of your Angular component.
4. Add CUSTOM_ELEMENTS_SCHEMA to the schemas array of your @Component decorator to allow the use of non-Angular custom elements.
5. Apply the *axLazyElement structural directive to the HTML element you want to lazy-load, passing the URL of the element bundle as the argument.

You can define beforeLoad and afterLoad hooks at three different levels of granularity. The service resolves which hook to use in the following order of precedence:

1. Method Level: Passed directly to loadElement() via hooksConfig.
2. Config Level: Defined within a specific ElementConfig object passed to addConfigs().
3. Global Level: Defined in the LAZY_ELEMENT_ROOT_OPTIONS provided to the service.

Hook Signatures:

• beforeLoad: A function that returns a Promise<void>. The script loading process will wait for this promise to resolve before appending the script to the document.
• afterLoad: A function that returns a Promise<void>. This is executed after the script has loaded.

The HooksConfig allows you to execute logic at specific points in the element lifecycle.

• beforeLoad: A function called before the element starts loading. It can be synchronous or return a Promise<void>.
• afterLoad: A function called after the element has successfully loaded.

Both hooks receive the tag (the HTML tag name) as an argument.

const hooks: HooksConfig = {
  beforeLoad: async (tag) => {
    await someAsyncSetup();
    console.log('Starting load for:', tag);
  },
  afterLoad: (tag) => {
    console.log('Finished loading:', tag);
  }
};

When using *axLazyElementDynamic, you can customize the UI during the loading and error phases using either template references or component classes.

Template-based (Recommended)

Pass an <ng-template> reference to axLazyElementDynamicLoadingTemplate or axLazyElementDynamicErrorTemplate.

Component-based

If no template is provided, the directive will attempt to use a loadingComponent or errorComponent configured globally via the LazyElementsLoaderService options or specifically for that tag via ElementConfig.

To use highlight.js within an Angular application via ngx-highlightjs, provide the HIGHLIGHT_OPTIONS token in your application configuration. You must define a coreLibraryLoader to load the core library and a languages object that maps language identifiers to dynamic import functions for their respective language modules.

import { HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';

export const HIGHLIGHT_JS_PROVIDER = {
  provide: HIGHLIGHT_OPTIONS,
  useValue: {
    coreLibraryLoader: () => import('highlight.js/lib/core'),
    languages: {
      typescript: () => import('highlight.js/lib/languages/typescript'),
      xml: () => import('highlight.js/lib/languages/xml'),
    },
  },
};

The library is designed to be used with corresponding major versions of Angular (e.g., @angular/core ^15.0.0 with @angular-extensions/elements ^15.0.0). Supported versions include:

• 9.x: Full Ivy support (uses renderers; use caution with SSR).
• 8.x: Partial Ivy support. Note that *axLazyElement works, but axLazyElementDynamic does NOT work with Ivy.
• 7.x
• 6.x: Install via npm i @angular-extensions/elements@^6.0.0.

If you receive a TypeError stating LazyElementsModule.forRoot() called twice. Lazy feature modules should use LazyElementsModule.forFeature() instead., it means you are attempting to initialize the root configuration in more than one place.

Resolution:

1. Ensure LazyElementsModule.forRoot() is only called in your main AppModule (or the entry point of your application).
2. For any subsequent modules or lazy-loaded routes that require element configurations, replace forRoot() with forFeature().

Use the LAZY_ELEMENT_CONFIGS injection token to provide an array of ElementConfig objects. This allows you to define the configuration for multiple web components/elements that the library will manage.

import { LAZY_ELEMENT_CONFIGS } from '@angular-extensions/elements';

// In your AppModule or component providers
providers: [
  {
    provide: LAZY_ELEMENT_CONFIGS,
    useValue: [
      { /* your ElementConfig configuration */ }
    ]
  }
]

The preload(tags?: string[]) method allows you to proactively load web component bundles.

• If called without arguments, it attempts to preload all currently registered configurations.
• If called with an array of strings, it only preloads the elements whose tag matches the provided list.

// Preload all registered elements
loaderService.preload();

// Preload only specific tags
loaderService.preload(['my-element', 'other-element']);