@sheldom/core

Native custom elements, with the lifecycle they were always missing.

@sheldom/core ships Component, a base class you extend instead of HTMLElement directly. It stays a real, standards-compliant custom element — just with the ergonomics you'd expect: clear lifecycle hooks, batched re-renders, Shadow DOM stylesheet adoption, and context that flows down your component tree.

✨ Features

🏗️ Still just HTMLElement

Component extends HTMLElement. No wrapper, no synthetic instance — instanceof HTMLElement is always true.

🎯 Clear lifecycle hooks

onBeforeMount, onMounted, onBeforeUnmount, onUnmounted — override what you need, skip what you don't.

🔁 Batched re-renders

requestUpdate() coalesces every synchronous call into a single re-render on the next microtask.

🎨 Automatic Shadow DOM styling

Declare static styles, and every ancestor class's stylesheet gets adopted into the shadow root, in inheritance order.

🌳 Context that crosses shadow boundaries

$context is inherited from the nearest ancestor Component, even through nested shadow roots.

🔌 Renders anything that fits the contract

render() returns a plain string or any TemplateBase — bring your own templating engine, or use @sheldom/dom.

📦 Install

npm install @sheldom/core

🚀 Usage

import { Component } from "@sheldom/core";

export default class Greeting extends Component {
    name = "world";

    onMounted() {
        console.log("mounted!");
    }

    render() {
        return `<p>Hello, ${this.name}!</p>`;
    }
}

customElements.define("my-greeting", Greeting);

Pair it with @sheldom/dom for reactive templates and scoped styles, and @sheldom/state for reactive fields that call requestUpdate() automatically:

import { Component } from "@sheldom/core";
import { css, html } from "@sheldom/dom";
import { state } from "@sheldom/state";

export default class Counter extends Component {
    static styles = css`
        button {
            padding: 0.5rem 1rem;
        }
    `;

    @state count = 0;

    render() {
        return html`
            <button @click=${() => this.count++}>Count: ${this.count}</button>
        `;
    }
}

All three come bundled together in sheldom, which is the recommended way to install the toolkit.

🌱 Part of the Sheldom toolkit

@sheldom/core only needs @sheldom/core-contracts and @sheldom/dom-contracts — it has no dependency on any specific rendering or state library. Most projects should install sheldom instead, which bundles this package with a rendering engine and reactive state.

📄 License

MIT — see LICENSE.