custom-element-lazy-loader

v1.3.1

Published

5 months ago

A tool for generating an entry point for lazy-loading custom elements/web components.

Downloads

128

0High
0Medium
0Low

breakstuff

Custom Element Lazy Loader

Create a single entry point to lazy-load your custom elements/web components as needed!

As components get loaded the component configurations get removed from the list and when all of the components have been loaded, the loader will shut off to help improve performance.

<body>
  <my-button>Button</my-button>
  <my-checkbox></my-checkbox>

  <!-- the lazy-loader will only load what gets used -->
  <script type="module" src="path/to/my/loader.js" />
</body>

Usage

This package includes two ways to generate the custom data config file:

calling a function in your build pipeline
as a plugin for the Custom Element Manifest Analyzer

Install

npm i -D custom-element-lazy-loader

Build Pipeline

import { generateCustomElementLoader } from "custom-element-lazy-loader";
import manifest from "./path/to/custom-elements.json";

const options = {...};

generateCustomElementLazyLoader(manifest, options);

CEM Analyzer

Set-up

Ensure the following steps have been taken in your component library prior to using this plugin:

Install and set up the Custom Elements Manifest Analyzer
Create a config file

Import

// custom-elements-manifest.config.js

import { customElementLazyLoaderPlugin } from "custom-element-lazy-loader";

const options = {...};

export default {
  plugins: [
    customElementLazyLoaderPlugin(options)
  ],
};

Once you run the analyzer, you should see a new file (loader.js by default) that users can import to load your components!

<script type="module" src="https://my-cdn.com/loader.js"></script>;

// or

import "my-project/loader.js";

Configuration

The configuration has the following parameters:

export type Options = {
  /** The template for creating the component's import path */
  importPathTemplate: (name: string, tagName: string) => string;
  /** Path to output directory. Default is `./` */
  outdir?: string;
  /** The of the loader file. Default is `loader.js` */
  fileName?: string;
  /** Additional components that may not be included in your Custom Elements Manifest */
  additionalComponents: ComponentConfig;
  /** Class names of any components you would like to exclude from the custom data */
  exclude?: string[];
  /** Enables logging during the component loading process */
  debug?: boolean;
  /** Adds a prefix to tag name */
  prefix?: string;
  /** Adds a suffix to tag name */
  suffix?: string;
  /** Component tag names that you would like to eager-load */
  eagerLoad: string[];
  /** Hides logs produced by the plugin */
  hideLogs?: boolean;
  /** Prevents plugin from executing */
  skip?: boolean;
};

Import Path Template

This option is required because it tells the loader where to find you component's module to load from. This should reference the path where you component is defined in the browser (using customElements.define() or some other mechanism). This path can also reference a resource outside of the project like a CDN.

Remember that this path is relative to the location of this file. For example, if this file is generated at the root of your project and the component definitions are in the dist/components directory could reference them like this:

{
  importPathTemplate: (name, tagName) =>
    `./dist/components/${name}/${tagName}.definition.js`;
}

This would generate imports for each of the components like:

'./dist/components/MyButton/my-button.definition.js'
'./dist/components/MyBadge/my-badge.definition.js'
'./dist/components/MyCard/my-card.definition.js'
...

Debugging

If you set the debug option to true, this will add additional logging during the loading process to help you identify any issues that are happening during the loading process. Additional logs include:

when a tag name is already registered
when there is an undefined component, but it is not in your list of components
when a component is successfully loaded
when a component fails to load (this one is always logged)

Adding Additional Components

If you are using additional components in your project that are not included in your Custom Elements Manifest (ie - third-party components), you can add them to your loader using the additionalComponents option. In this example, I am importing components from Shoelace that are also being used in my project.

{
  additionalComponents: {
    "sl-button": {
      importPath:
        "https://cdn.jsdelivr.net/npm/@shoelace-style/[email protected]/cdn/components/button/button.js",
    },
    "sl-icon": {
      importPath:
        "https://cdn.jsdelivr.net/npm/@shoelace-style/[email protected]/cdn/components/icon/icon.js",
    },
    "sl-input": {
      importPath:
        "https://cdn.jsdelivr.net/npm/@shoelace-style/[email protected]/cdn/components/input/input.js",
    },
  }
}

The component configurations use the following type:

type ComponentConfig = {
  /** The key is the component's tag-name (in lower-case) */
  [key: string]: {
    /** The path to the module where the component is defined */
    importPath: string;
    /** Any components used within this component that will be registered at the same time */
    dependencies?: string[];
  };
};

Runtime Configuration

If you are using the loader post-build and need to add configurations, you can modify some of the options using the updateConfig function. The function takes in a config parameter that has the following options:

/** Configuration options for the `updateConfig` function */
type RuntimeConfiguration = {
  /** Additional components that may not be included in your Custom Elements Manifest */
  components?: ComponentConfig;
  /** The root element to observe for your custom elements */
  rootElement?: Element;
  /** Component tag names that you would like to eager-load */
  eagerLoad: string[];
};

NOTE: The updateConfig function is async, so you can await it if you want to ensure load order.

Adding Components

This option allows you to add additional custom elements to watch for that may not have been included in the original build of the loader. This is similar to the additionalComponents option, but it adds them at runtime.

Setting the Root Element

The loader will observe the document body for any new components that get added, but if you know your components will only be added to a subset of the DOM, you can specify an element to observe the children in to improve performance.

{
  rootElement: document.querySelector("#my-app");
}

Eager-Loading Components

There may be instances where you want certain components loaded as soon as possible. Both the generator and runtime configs accept an eagerLoad option. This is a string array of the tag names you would like to eager-load (load immediately) from your list of components.

Scoping Components

If you are using custom tag names with either a prefix or suffix to prevent tag name collisions, you can configure the lazy-loader watch for your scoped tags. Both the build and runtime configurations accept prefix and suffix options to update the component list with your specified tag names.

For example, setting the prefix option to prefix_ will update the tag list so the loader will watch for prefix_my-element.