{"id":22160357,"url":"https://github.com/rozek/updatable-custom-elements","last_synced_at":"2025-06-30T22:04:56.667Z","repository":{"id":114382978,"uuid":"526819955","full_name":"rozek/updatable-custom-elements","owner":"rozek","description":"partial \"hot module replacement\" for \"Custom Elements\"","archived":false,"fork":false,"pushed_at":"2022-08-30T07:43:01.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-30T22:02:12.448Z","etag":null,"topics":["custom-elements","hot-module-reloading","hot-module-replacement","hot-reload","hot-reloading"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rozek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-20T04:00:06.000Z","updated_at":"2022-08-20T05:30:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"0cc7f6a3-8236-4403-a002-81ca7fffa895","html_url":"https://github.com/rozek/updatable-custom-elements","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rozek/updatable-custom-elements","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozek%2Fupdatable-custom-elements","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozek%2Fupdatable-custom-elements/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozek%2Fupdatable-custom-elements/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozek%2Fupdatable-custom-elements/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rozek","download_url":"https://codeload.github.com/rozek/updatable-custom-elements/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozek%2Fupdatable-custom-elements/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262857258,"owners_count":23375487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-elements","hot-module-reloading","hot-module-replacement","hot-reload","hot-reloading"],"created_at":"2024-12-02T04:07:32.717Z","updated_at":"2025-06-30T22:04:56.520Z","avatar_url":"https://github.com/rozek.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# updatable-custom-elements #\n\npartial \"hot module replacement\" for \"Custom Elements\"\n\n\"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](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)\".\n\n`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.\n\n**NPM users**: please consider the [Github README](https://github.com/rozek/updatable-custom-elements/blob/main/README.md) for the latest description of this package (as updating the docs would otherwise always require a new NPM package version)\n\n\u003e 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.\n\n## Technical Background ##\n\nIn order to understand the benefits and limitations of `updatable-custom-elements`, it is important to know how they work:\n\n* when a given class is registered as a \"custom element\" for the first time, it is registered as usual\n* but whenever a class is registered for an already existing \"custom element\", `updatable-custom-elements` simply replaces all class and instance properties and methods\n\nConsequently, **the following details are left untouched**:\n\n1. as the class itself is not changed, its **inheritance chain is kept**,\n2. **the constructor remains unchanged** as well,\n3. since the **custom element callbacks** seem to be cached internally, they **cannot be updated** either\n4. and since the observable attributes seem to be cached as well, **changing the getter for `observedAttributes` has no effect**.\n\nRestrictions 2 and 3 can easily be circumvented by providing redirections in the class implementation:\n\n```javascript\nclass updatableElement extends HTMLElement {\n  constructor () {\n    super()\n    this.initialize()\n  }\n  \n  connectedCallback ()    { this.onConnect() }\n  disconnectedCallback () { this.onDisconnect() }\n  adoptedCallback ()      { this.onAdopt() }\n\n  attributeChangedCallback (Name, oldValue, newValue) {\n    this.onAttributeChange(Name, oldValue, newValue)\n  }\n  \n  initialize ()   { ... }\n  \n  onConnect ()    { ... }\n  onDisconnect () { ... }\n  onAdopt ()      { ... }\n  \n  onAttributeChange (Name, oldValue, newValue) { ... }\n}\n```\n\nAdditionally, the typical caveats of \"hot module replacement\" apply here as well:\n\n* 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\")\n* 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 \n\nIf you still want to update \"custom elements\" at runtime, just read on.\n\n## Installation ##\n\n`updatable-custom-elements` may be used as an ECMAScript module (ESM) or explicitly loaded by inserting a `\u003cscript\u003e` element into the web document.\n\nFor the ESM variant, install the package into your build environment using [NPM](https://docs.npmjs.com/) with the command\n\n```\nnpm install updatable-custom-elements\n```\n\nand `import` it into your code whereever needed\n\n```javascript\nimport \"updatable-custom-elements\"\n```\n\nOtherwise, load the plain script file directly\n\n```html\n\u003cscript src=\"https://unpkg.com/updatable-custom-elements\"\u003e\u003c/script\u003e\n```\n\n## Usage ##\n\nOnce loaded or imported, `updatable-custom-elements` work silently in the background - just define (and use) your \"custom elements\" as usual:\n\n```javascript\nclass A extends HTMLElement {\n  ...\n}\ncustomElements.define('custom-element',A)\n\nclass B extends HTMLElement {\n  ...\n}\ncustomElements.define('custom-element',B)\n```\n\n## Build Instructions ##\n\nYou may easily build this package yourself.\n\nJust install [NPM](https://docs.npmjs.com/) according to the instructions for your platform and follow these steps:\n\n1. either clone this repository using [git](https://git-scm.com/) or [download a ZIP archive](https://github.com/rozek/updatable-custom-elements/archive/refs/heads/main.zip) with its contents to your disk and unpack it there \n2. open a shell and navigate to the root directory of this repository\n3. run `npm install` in order to install the complete build environment\n4. execute `npm run build` to create a new build\n\nYou may also look into the author's [build-configuration-study](https://github.com/rozek/build-configuration-study) for a general description of his build environment.\n\n## License ##\n\n[MIT License](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frozek%2Fupdatable-custom-elements","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frozek%2Fupdatable-custom-elements","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frozek%2Fupdatable-custom-elements/lists"}