Radiant
@ecopages/radiant is an ultra-minimalist library for building reactive Web Components. It is designed to play perfectly with Ecopages' dependency management and SSR capabilities.
Introduction
Radiant uses standard CUSTOM Elements with a thin layer of decorators to handle reactivity and DOM queries. Use it when you need interactivity without the overhead of a full framework.
Component Example
/** @jsxImportSource @ecopages/jsx */
import { RadiantElement, customElement, onEvent, prop, query } from '@ecopages/radiant';
@customElement('radiant-counter')
export class RadiantCounter extends RadiantElement {
@prop({ type: Number, defaultValue: 0 }) value!: number;
@query<HTMLSpanElement>({ selector: 'span' }) display!: HTMLSpanElement | null;
@onEvent({ type: 'click', selector: 'button.increment' })
inc() {
this.value += 1;
}
override render() {
return (
<div>
<span>{this.value}</span>
<button class="increment" type="button">
Increment
</button>
</div>
);
}
}Decorators such as @prop need a RadiantElement host. A plain HTMLElement subclass has none of the reactive machinery they rely on.
Decorators
@customElement(tag: string)
Registers the class as an autonomous custom element with the given tag name.
@prop(options)
Defines a reactive public property. It is also an attribute, named after the kebab-case property name unless attribute says otherwise. type, defaultValue, and transform must agree with the declared field type. A change schedules an update of the host.
@onEvent(options)
Declaratively attaches an event listener, with type and one target: selector or ref for delegation on the host, or window, document, or mediaQuery. Delegated listeners need an event that bubbles.
@query(options)
Reads a single element by selector or ref each time the field is accessed. The field type is T | null, or T[] with all: true, so guard each use.
See the Radiant docs for @state, @signal, @attr, @bindTo, and the rest of the decorator set.
Using with Ecopages
Radiant hosts in JSX apps use Ecopages JSX (ecopagesJsxPlugin() enables Radiant SSR by default). See Creating Components for the full eco.component() pattern.
- Put element registration in a
*.script.tsfile (callcustomElements.defineor use@customElement). - Wrap the host in
eco.component()and declare the script withssr: trueso Ecopages evaluates it on the server before SSR. Useimport typefrom the script module when you only need props—no separate value import in the wrapper file. - Import the wrapper from pages; Ecopages discovers local
eco.component()imports automatically.
counter.script.ts:
export type CounterProps = { count?: number };
export class CounterElement extends HTMLElement {
static observedAttributes = ['count'];
connectedCallback() {
this.textContent = String(this.getAttribute('count') ?? 0);
}
attributeChangedCallback() {
this.textContent = String(this.getAttribute('count') ?? 0);
}
}
if (!customElements.get('radiant-counter')) {
customElements.define('radiant-counter', CounterElement);
}counter.tsx:
import { eco } from '@ecopages/core';
import type { CounterProps } from './counter.script';
export const Counter = eco.component({
dependencies: {
scripts: [{ src: './counter.script.ts', ssr: true }],
},
render: ({ count = 0 }: CounterProps) => <radiant-counter count={count} />,
});Add lazy on the script entry when browser delivery should wait for idle, interaction, or visibility. lazy does not skip server registration when ssr: true is set.