In the last post in this series, we took a journey through some of the web component technologies that have been popular over the last 10 years. This post wrapped up by providing a brief introduction to the modern web component APIs and specifications, which I contend are the future of building reusable components for the web. In the next few posts in this series, we’ll look into how Aurelia uses several of the web component APIs to implement some interesting features like templated components (with Shadow DOM slots). We’ll also look at how Aurelia enables the use of vanilla and Polymer web components right within your Aurelia SPAs. In This post, we look at the first web component API supported by Aurelia, HTML Imports.

HTML Imports and the Require Statement

HTML Imports define a method for loading other HTML documents into a parent document. This is very useful in the context of web components when you begin to think of a page as nothing but a hierarchy of bite sized UI widgets composed together. The main benefits of HTML imports are as follows:

• Web native loading system: Where there are many other mechanisms out there for achieving a similar result, HTML Imports are designed to be built into browsers going forward, which ideally will allow you to load components without the need for any third party dependencies. If you need a third party loader to load modules, then how do you load the loader? Just a thought.
• Dependency Management: Dependent components are loaded in the order you expect. For example, if you import component google-map which imports say map then map should be loaded first to set up the dependencies. HTML imports provide these out of the box.
• Native HTML parsing
• De-duplication of dependencies: If you imagine a dependency graph where two parent components rely on the same child component, the child component will only be loaded once.

You can use HTML imports by adding a link rel="import" tag in the head of your page as shown in the below example where we import an info-card component into the page. One of the neat things about HTML imports is that you can include everything that the component needs inside the referenced HTML page. This provides consumers of your component with a straightforward way to bring it into your application:

For example, Google provides a Google maps Polymer component which makes it trivial to add Google maps to your website without the need for an IFrame. All that’s required is to include an HTML import statement to load the web component:

<link rel="import" href="google-map.html">

This is all well and good, but how does it apply to Aurelia? Like many subsystems within the Aurelia framework, Aurelia’s template loading system uses a plugin model. There is a base template loader called loader which defines the common template loading interface. Other loaders, including the text-template-loader, aurelia-webpack-loader and html-import-template-loader, each implement this standard interface, as shown in the below diagram:

As you can see, Aurelia supports an html-import-template-loader which is specifically designed to allow you to include vanilla and Polymer web components easily within your Aurelia applications. From the HTML import template loader source this loader works by creating a new link rel='import' element as we saw in the above google-map component example and asynchronously loads the target HTML component:

To use this loader within your Aurelia application it’s simply a matter of adding the plugin to Aurelia’s bootstrap process in the main.js file:

If you’re interested in learning more about using Polymer components this great guide on the Aurelia Hub, which takes you through a step by step process to add Polymer components to an Aurelia project with the aid of the aurelia-html-import-template-loader.

One caveat to all of this is that the future of HTML imports is uncertain at this point. While Polymer adopted HTML imports whole heartedly, it was pretty much the only mainstream framework to do so. As such, with version 3 of Polymer, Google has announced that they’re now moving towards ES6 modules as their preferred approach to template loading instead of HTML imports. Whilst this won’t have much of an impact on the Aurelia development story (due to Aurelia’s flexible plugin model for loading components) it does mean that it’s a space to watch in the near future.