Comprehensive Guide On Using Angular Custom Elements

Integrating modern web components into legacy projects can be a daunting task. This article provides a comprehensive guide on how to leverage Angular's custom elements to seamlessly inject reusable components into existing codebases. While the official Angular documentation offers a starting point, this guide delves deeper into the practical aspects of building and deploying custom elements, addressing common challenges and providing actionable solutions.

Understanding Angular Custom Elements

Angular custom elements are essentially Angular components packaged as standard web components, also known as custom elements. These elements adhere to the Web Components standards, allowing them to be used in any web application, regardless of the underlying framework (or lack thereof). This interoperability makes them ideal for injecting new functionality into legacy projects built with older technologies.

The beauty of Angular custom elements lies in their self-contained nature. They encapsulate their functionality, styling, and behavior, making them easy to reuse and maintain. Once built, a custom element can be used like any other HTML element, such as <button> or <div>, simplifying integration into existing workflows.

Benefits of Using Angular Custom Elements

There are several compelling reasons to consider Angular custom elements for your project:

• Reusability: Custom elements can be used across different projects and frameworks, promoting code sharing and reducing development time.
• Encapsulation: They encapsulate their internal logic and styling, preventing conflicts with existing code and ensuring a clean separation of concerns.
• Interoperability: Custom elements work seamlessly with any web framework or library that supports the Web Components standards.
• Maintainability: By encapsulating functionality into reusable components, you can simplify maintenance and updates.
• Gradual Modernization: Custom elements allow you to gradually modernize your legacy applications by introducing new features as self-contained components.

Setting Up Your Angular Project for Custom Elements

Before diving into code, let's set up your Angular project to build custom elements. We'll start with a new Angular project, but you can adapt these steps to an existing one. Use the Angular CLI to create a new project:

npm install -g @angular/cli
ng new my-custom-element-project
cd my-custom-element-project

Once the project is created, you'll need to make a few adjustments to your angular.json file. This file configures various aspects of your Angular project, including how it's built and served. Specifically, you'll need to configure the build process to output a single JavaScript file containing your custom element's code.

Configuring angular.json

Open your angular.json file and locate the projects section. Within your project's configuration, find the architect section, and then the build target. Modify the options section of the build target to include the following:

"options": {
  "outputPath": "dist/my-custom-element-project",
  "index": "src/index.html",
  "main": "src/main.ts",
  "polyfills": "src/polyfills.ts",
  "tsConfig": "tsconfig.app.json",
  "assets": [
    "src/favicon.ico",
    "src/assets"
  ],
  "styles": [
    "src/styles.css"
  ],
  "scripts": [],
  "buildOptimizer": false,
  "vendorChunk": false,
  "extractLicenses": false,
  "sourceMap": true,
  "optimization": false,
  "namedChunks": true
}

The key configurations here are buildOptimizer, vendorChunk, extractLicenses, sourceMap, optimization, and namedChunks. Setting these to false ensures that Angular outputs a single, easily deployable JavaScript file.

Next, you'll need to add a new script to your package.json file to concatenate the generated JavaScript files into a single bundle. Open your package.json and add the following script to the scripts section:

"scripts": {
  "ng": "ng",
  "start": "ng serve",
  "build": "ng build",
  "watch": "ng build --watch --configuration development",
  "test": "ng test",
  "build:elements": "ng build --output-hashing none && node concat.js"
}

This script uses ng build to build your project and then executes a Node.js script (concat.js) to concatenate the output files. Now, let's create the concat.js file in the root of your project:

// concat.js
const fs = require('fs-extra');
const concat = require('concat');

(async function build() {
  const files = [
    './dist/my-custom-element-project/runtime.js',
    './dist/my-custom-element-project/polyfills.js',
    './dist/my-custom-element-project/scripts.js',
    './dist/my-custom-element-project/main.js'
  ];

  await fs.ensureDir('elements');
  await concat(files, 'elements/my-custom-element.js');
  console.log('Custom element created successfully!');
})();

This script reads the generated JavaScript files, concatenates them into a single file named my-custom-element.js in the elements directory, and logs a success message. You'll also need to install the fs-extra and concat packages:

npm install fs-extra concat --save-dev

Building Your First Angular Custom Element

Now that your project is set up, let's create your first custom element. Start by creating a new component using the Angular CLI:

ng generate component my-element

This command creates a new component named MyElementComponent in the src/app/my-element directory. Open my-element.component.ts and add your component's logic and template. For this example, let's create a simple component that displays a greeting:

// my-element.component.ts
import { Component, Input, ViewEncapsulation } from '@angular/core';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-my-element',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div class="my-element">
      <strong>Hello from my custom element!</strong>
      <p>Greeting: {{ greeting }}</p>
    </div>
  `,
  styles: [`
    .my-element {
      border: 1px solid blue;
      padding: 10px;
      margin: 10px;
    }
  `],
  encapsulation: ViewEncapsulation.ShadowDom
})
export class MyElementComponent {
  @Input() greeting: string = 'Default Greeting';
}

Key things to notice:

• @Input() greeting: string: This declares an input property that allows the parent component or the host page to pass data into the custom element.
• encapsulation: ViewEncapsulation.ShadowDom: This is crucial for custom elements. It uses Shadow DOM to encapsulate the component's styles, preventing them from interfering with the styles of the host page.

Next, you need to convert this component into a custom element. Open your app.module.ts (or app.config.ts if you're using standalone components) and add the following code:

// app.module.ts (example with NgModule)
import { NgModule, Injector } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { createCustomElement } from '@angular/elements';
import { MyElementComponent } from './my-element/my-element.component';

@NgModule({
  declarations: [
    AppComponent,
    MyElementComponent
  ],
  imports: [
    BrowserModule
  ],
  providers: [],
  bootstrap: [AppComponent],
  // ADD THIS LINE
  entryComponents: [MyElementComponent]
})
export class AppModule {
  constructor(private injector: Injector) {}

  ngDoBootstrap() {
    const myCustomElement = createCustomElement(MyElementComponent, { injector: this.injector });
    customElements.define('my-custom-element', myCustomElement);
  }
}

// app.config.ts (example with standalone components)
import { ApplicationConfig, Injector } from '@angular/core';
import { createCustomElement } from '@angular/elements';
import { provideRouter } from '@angular/router';

import { MyElementComponent } from './my-element/my-element.component';
import { routes } from './app.routes';
import { BrowserModule } from '@angular/platform-browser';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

export const appConfig: ApplicationConfig = {
  providers: [provideRouter(routes)]
};

(async () => {
  const platformRef = platformBrowserDynamic();
  const injector: Injector = platformRef.injector;

  const myCustomElement = createCustomElement(MyElementComponent, { injector });
  customElements.define('my-custom-element', myCustomElement);

  await platformRef.bootstrapModule(MyElementComponent);
})();

Let's break down what this code does:

• createCustomElement: This function from @angular/elements converts your Angular component into a custom element class.
• customElements.define: This registers the custom element with the browser, making it available for use in your HTML.
• 'my-custom-element': This is the tag name you'll use in your HTML to reference the custom element (e.g., <my-custom-element>).
• entryComponents (NgModule approach): This tells Angular to compile the component even if it's not directly referenced in a template. This is crucial for custom elements.
• Bootstrap using platformBrowserDynamic (standalone approach): This is required to initialize the component for the standalone approach.

Finally, remove the selector <app-my-element> from app.component.html since you will be using the custom element my-custom-element instead.

Building and Deploying Your Custom Element

Now it's time to build your custom element. Run the following command:

npm run build:elements

This command executes the build:elements script you added to your package.json file. It first builds your Angular project and then concatenates the generated JavaScript files into a single file in the elements directory.

To use your custom element in a legacy project, simply include the generated JavaScript file in your HTML:

<!DOCTYPE html>
<html>
<head>
  <title>My Legacy Project</title>
</head>
<body>
  <h1>Welcome to my legacy project!</h1>
  <my-custom-element greeting="Hello from the legacy project!"></my-custom-element>
  <script src="elements/my-custom-element.js"></script>
</body>
</html>

Notice how you're using the <my-custom-element> tag just like any other HTML element. You're also passing a value to the greeting input property.

Advanced Custom Element Techniques

While the basic example above demonstrates the core concepts, there are several advanced techniques you can use to enhance your custom elements.

Event Handling

Custom elements can emit custom events that the host page can listen to. To emit an event, use the EventEmitter class from @angular/core:

// my-element.component.ts
import { Component, Input, Output, EventEmitter, ViewEncapsulation } from '@angular/core';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-my-element',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div class="my-element">
      <strong>Hello from my custom element!</strong>
      <p>Greeting: {{ greeting }}</p>
      <button (click)=