codewithkyle / lazy-loader

A lightweight Web Component based lazy loading library.

Lazy Loader

A lightweight (~2kb) Web Component based lazy loading library.

Install

Install via NPM:

npm i -S @codewithkyle/lazy-loader

Or via CDN:

import { configure, update, mount, css } from "https://cdn.jsdelivr.net/npm/@codewithkyle/lazy-loader@1/lazy-loader.min.mjs";

<script src="https://cdn.jsdelivr.net/npm/@codewithkyle/lazy-loader@1/lazy-loader.min.js">

Usage

ES Module

import { configure, update, mount, css } from "https://cdn.jsdelivr.net/npm/@codewithkyle/lazy-loader@1/lazy-loader.min.mjs";

// Start the lazy loading process by configuring the default locations for your JS and CSS files
configure({
    jsDir: "/js",
    cssDir: "/css",
    default: "lazy", // optional
    lazierCSS: false, // optional
});

// Alternatively if the default settings (seen above) are okay you could simply call the update function instead
// You can call the update function at any time
update();

// Manually mount new components
import { MyCustomElement } from "./my-custom-element.js";
mount("my-custom-element", MyCustomElement); // returns a promise

// Alternatively if the components file name matches the tag name the library can dynamically import the script from the JS directory (see configure function)
mount("my-custom-element");

// Manually lazy load CSS files
css("exmaple.css"); // returns a promise

// Alternatively you can load multiple files at once
css(["example-one", "examle-two.css", "https://cdn.example.com/example-two.css", "../../relative-path-example.css"]);

Common JS

LazyLoader.configure({
    jsDir: "/",
    cssDir: "/",
    default: "lazy", // optional
    lazierCSS: false, // optional
});
LazyLoader.update();
LazyLoader.mount("my-custom-element")

Interfaces

type Loading = "eager" | "lazy";

interface LazyLoaderSettings {
    cssDir?: string;
    jsDir?: string;
    default?: Loading;
    lazierCSS: boolean;
};

declare const configure: (settings?:Partial<LazyLoaderSettings>) => void;
declare const update: () => void;
declare const mount: (tagName:string, constructor?: CustomElementConstructor) => Promise<void>;
declare const css: (files:string|string[]) => Promise<void>;

HTML Attributes

<!-- Lazy load Web Components by tagging custom elements with the web-component attribute. -->
<!-- In this example the custom-element.js file will be imported from the configured jsDir directory. -->
<custom-element web-component></custom-element>

<!-- You can override the default import behavior by providing a custom file name, relative path, or a URL. -->
<custom-element web-component="custom-file-name.js"></custom-element>

<!-- By default components are loaded and mounted when they enter the viewport. -->
<!-- You can bypass the lazy loader by using the loading attribute. -->
<custom-element web-component loading="eager"></custom-element>

<!-- You can lazy load CSS by attaching the css attribute to any element within the documents body. -->
<!-- You can load multiple files using a whitespace separator. Note that the .css file extenstion is optional. -->
<div class="my-awesome-class" css="awesome-transitions awesome.css"></div>

lazy-loader's Issues

Lazier CSS loading

Currently the 'lazy' CSS is tied to the update() function call. Instead I think the CSS should only be loaded when the component is mounted and it should be a blocking process. We should not mount the component until after all the CSS requests have resolved. Developers would still be able to instantly invoke the lazy CSS loading functionality by using the css() function.

Why

The current functionality goes against the core principles of this library (in a way). We should only be loading the resources we need when we need them. The reason we loaded all the CSS upfront was to prevent styled content flashing. If we block the components mount behavior until all CSS requests have resolved we can avoid this unwanted side effect of lazy loading CSS.

Preserving backwards compatibility

This new behavior should sit behind a new config flag:

{
  lazierCSS: true
}

Eager by default

Developers should be able to set the default behavior to eager or lazy (use lazy by default). The loading attribute should then override this behavior.

Why?

When pairing this library with something like HTMX it would be helpful to automatically load/mount all components when the update() method is invoked.