lume

Small reactive components for existing HTML.

Lume lets you attach reactive TypeScript components to existing HTML — no renderer, no Virtual DOM, no JSX. It is calm, clean, and browser-native.

Bundle Size

| Format | Size | Gzipped | | -------------- | ------- | ---------- | | ESM (minified) | ~2.4 kB | ~1 kB | | ESM | ~5.2 kB | ~1.5 kB | | CJS | ~6.5 kB | ~1.9 kB |

Installation

npm install @beardcoder/lume
# or
bun add @beardcoder/lume

Quick Start

HTML:

<div data-lume="disclosure" data-lume-id="main-menu">
  <button data-lume-part="button" aria-expanded="false">Toggle</button>
  <div data-lume-part="panel">Content</div>
</div>

TypeScript:

import { createLume, defineComponent } from "@beardcoder/lume";

const disclosure = defineComponent(({ part, signal, on, effect }) => {
  const button = part("button");
  const panel = part("panel");
  const open = signal(false);

  on(button, "click", () => open.update(v => !v));

  effect(() => {
    panel.hidden = !open();
    button.setAttribute("aria-expanded", String(open()));
  });

  return {
    show: () => open.set(true),
    hide: () => open.set(false),
  };
});

const app = createLume();
app.component("disclosure", disclosure).mount();

const menu = app.require("main-menu");
menu.hide();

HTML Attributes

| Attribute | Purpose | | --------------- | -------------------------------------------- | | data-lume | Marks the root element of a component | | data-lume-part| Marks a named element or template inside | | data-lume-id | Assigns an ID so the component API can be retrieved |

Components

Define a component using defineComponent. It receives a context object and returns its public API.

import { defineComponent } from "@beardcoder/lume";

export default defineComponent(({ part, signal, effect, on }) => {
  // ...
  return { /* public API */ };
});

Register and mount:

import { createLume } from "@beardcoder/lume";
import myComponent from "./my-component";

const app = createLume();
app.component("my-component", myComponent).mount();

Component Context

| Property | Description | | ----------------- | --------------------------------------------------- | | root | The component root element | | part(name) | Finds one [data-lume-part="name"] inside root | | parts(name) | Finds all matching parts | | template(name) | Returns a factory that clones a <template> part | | signal(initial) | Creates a reactive signal | | computed(fn) | Creates a derived signal | | effect(fn) | Runs fn immediately and again when signals change | | untrack(fn) | Reads signals without subscribing the effect | | on(target, event, handler, options?) | Adds an event listener with auto cleanup | | cleanup(fn) | Registers a cleanup function | | emit(name, detail?) | Emits a local app event | | listen(name, handler) | Listens to a local app event | | global.emit(name, detail?) | Emits a global event (shared across apps) | | global.listen(name, handler) | Listens to a global event |

Signals & Effects

const count = signal(0);   // create
count();                   // read (subscribes the surrounding effect)
count.peek();              // read without subscribing
count.set(1);              // write
count.update(v => v + 1);  // transform

effect(() => {
  console.log("count is", count()); // runs on change
});

// Read multiple signals untracked
import { untrack } from "@beardcoder/lume";
const total = untrack(() => price() * quantity());

Events

Local (per-app)

// Inside a component
emit("my-event", { value: 42 });
listen("my-event", (detail) => console.log(detail));

// On the app
app.emit("my-event", { value: 42 });
app.listen("my-event", (detail) => console.log(detail));

Global (shared across apps)

// Inside a component
global.emit("global-event", payload);
global.listen("global-event", handler);

Templates

Use native <template> elements with data-lume-part:

<div data-lume="toast" data-lume-id="toaster">
  <template data-lume-part="item">
    <div class="toast" role="status">
      <span data-lume-part="message"></span>
      <button type="button">Close</button>
    </div>
  </template>
</div>

const createItem = template("item");
const frag = createItem(); // cloned DocumentFragment
root.appendChild(frag);

Public API via Return

Expose your component's public methods by returning an object from defineComponent. Access it via app.get(id) or app.require(id).

const menu = app.require<MenuApi>("main-menu");
menu.hide();

• app.get(id) — returns T | undefined
• app.require(id) — returns T or throws a clear error

Plugins

A plugin is just a function that receives the app:

function myPlugin(app) {
  app.component("tooltip", tooltip);
}

app.use(myPlugin);

What Lume Does Not Do

Lume intentionally has no:

• Virtual DOM or renderer
• JSX or custom templates
• Directives (data-lume-show, data-lume-on, etc.)
• Router, store, or SSR
• Animation APIs
• Devtools or inspect
• Framework-style contracts or aliases

HTML marks structure. TypeScript contains the logic.

License

MIT