Grundlage

A small, zero-dependency library for building web components with tagged template literals.

Installation

npm install grundlage

Concepts

Components as Generators

Components are defined using generator functions. This gives you explicit control over the component lifecycle: setup runs until you yield a render function, the host element is passed in as the first argument, and the return value is your cleanup.

render(generator, options?) returns a custom element constructor — register it with customElements.define.

import { render, html } from "grundlage";

customElements.define(
	"async-component",
	render(async function* (host) {
		yield html`<p>loading</p>`;

		try {
			const data = await fetch("...");
			yield html`<p>name: ${data.name}, age: ${data.age}</p>`;
		} catch (error) {
			yield html`<p>error: ${error}</p>`;
		}

		return () => {
			console.log("cleanup");
		};
	}),
);

Each yield evaluates to the host element, so inner generators or render functions can capture it without closing over the outer parameter:

render(function* () {
	const host = yield () => html`<p>hello</p>`;
	host.addEventListener("click", () => host.update());
});

Yielded inner generators and render functions also receive the host element as their first argument — handy for nested rendering without re-capturing scope.

render(function* (host) {
	yield function* (innerHost) {
		// innerHost === host
		yield html`<p>nested</p>`;
		return () => console.log("inner cleanup");
	};
});

Templating

The html tagged template literal parses your markup once and caches the result. Subsequent renders only update the dynamic parts.

html`<div class="card ${isActive ? "active" : ""}">
	<h2>${title}</h2>
	<p>${description}</p>
</div>`;

props

Managing props on web-components is tedious. As attributes they are always strings and are not that ergonomic to get to. Other types can be saved as properties on the element itself, but requires different handling. As a helper, we have a props function that takes an element and an object of Keys and Constructors. They will be used for typing and validating the input regardless of attribute or property. If the value is missing, a fallback can be provided.

render(function* (host) {
	const result = props(host, {
		label: String,
		count: Number,
		disabled: Boolean,
		callback: Function,
		items: Array,
		missing: [String, "default"],
	});
});

Supported bindings:

• Content: <p>${text}</p>
• Attributes: <div class=${className}>
• Mixed attributes: <div class="static ${dynamic}">
• Event handlers: <button onClick=${handler}>
• Lists: <ul>${items.map(i => html${i})}</ul>
• Nested templates: <div>${showDetails ? html... : null}</div>
• Dynamic tags: <${tagName}>content</${tagName}>
• Raw content (style/script/textarea): <style>${css}</style>

Reactivity

Grundlage uses a hash-based change detection system. When you call host.update() on the host element, it compares hashes of each expression to determine what actually changed.

This means:

• Primitives are compared by value
• Arrays and objects are compared by content (shallow)
• Nested templates are compared by structure and values
• DOM updates only happen for expressions that changed

render(function* (host) {
	const items = [];

	const add = (text) => {
		items.push({ id: Date.now(), text });
		host.update();
	};

	yield () => html`
		<ul>
			${items.map((item) => html`<li>${item.text}</li>`)}
		</ul>
	`;
});