npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

updatable-custom-elements

v0.1.2

Published

partial "hot module replacement" for "Custom Elements"

Downloads

15

Readme

updatable-custom-elements

partial "hot module replacement" for "Custom Elements"

"Hot Module Replacement" (or "Hot Module Reloading") is a well-established mechanism for the development of web applications - it works fine, but only as long as you don't try to replace the definitions of "custom elements".

updatable-custom-elements partially implements "Hot Module Reloading" for "custom elements" with the idea to facilitate development and debugging, but not for module replacement at runtime.

NPM users: please consider the Github README for the latest description of this package (as updating the docs would otherwise always require a new NPM package version)

Just a small note: if you like this module and plan to use it, consider "starring" this repository (you will find the "Star" button on the top right of this page), so that I know which of my repositories to take most care of.

Technical Background

In order to understand the benefits and limitations of updatable-custom-elements, it is important to know how they work:

  • when a given class is registered as a "custom element" for the first time, it is registered as usual
  • but whenever a class is registered for an already existing "custom element", updatable-custom-elements simply replaces all class and instance properties and methods

Consequently, the following details are left untouched:

  1. as the class itself is not changed, its inheritance chain is kept,
  2. the constructor remains unchanged as well,
  3. since the custom element callbacks seem to be cached internally, they cannot be updated either
  4. and since the observable attributes seem to be cached as well, changing the getter for observedAttributes has no effect.

Restrictions 2 and 3 can easily be circumvented by providing redirections in the class implementation:

class updatableElement extends HTMLElement {
  constructor () {
    super()
    this.initialize()
  }
  
  connectedCallback ()    { this.onConnect() }
  disconnectedCallback () { this.onDisconnect() }
  adoptedCallback ()      { this.onAdopt() }

  attributeChangedCallback (Name, oldValue, newValue) {
    this.onAttributeChange(Name, oldValue, newValue)
  }
  
  initialize ()   { ... }
  
  onConnect ()    { ... }
  onDisconnect () { ... }
  onAdopt ()      { ... }
  
  onAttributeChange (Name, oldValue, newValue) { ... }
}

Additionally, the typical caveats of "hot module replacement" apply here as well:

  • since any existing instances of the affected "custom element" are left untouched, their state remains (in fact, this is often a fundamental reason for "hot module replacement")
  • in particular, any already registered event handlers are still present and react on incoming events - if you plan to update event handling at runtime, redirects within the registered handlers may help here as well

If you still want to update "custom elements" at runtime, just read on.

Installation

updatable-custom-elements may be used as an ECMAScript module (ESM) or explicitly loaded by inserting a <script> element into the web document.

For the ESM variant, install the package into your build environment using NPM with the command

npm install updatable-custom-elements

and import it into your code whereever needed

import "updatable-custom-elements"

Otherwise, load the plain script file directly

<script src="https://unpkg.com/updatable-custom-elements"></script>

Usage

Once loaded or imported, updatable-custom-elements work silently in the background - just define (and use) your "custom elements" as usual:

class A extends HTMLElement {
  ...
}
customElements.define('custom-element',A)

class B extends HTMLElement {
  ...
}
customElements.define('custom-element',B)

Build Instructions

You may easily build this package yourself.

Just install NPM according to the instructions for your platform and follow these steps:

  1. either clone this repository using git or download a ZIP archive with its contents to your disk and unpack it there
  2. open a shell and navigate to the root directory of this repository
  3. run npm install in order to install the complete build environment
  4. execute npm run build to create a new build

You may also look into the author's build-configuration-study for a general description of his build environment.

License

MIT License