Hephaestus Documentation

Introduction

Hephaestus is a lightweight JavaScript library that makes DOM creation and archetyping concise, expressive, and safe. It provides a fully programmatic API for building DOM nodes and defining reusable component archetypes without dependencies or frameworks.

• Builder function hepha.relic() for all major HTML tags.
• A robust archetype engine with deep-merging override logic.
• Reactive state system for automatic DOM updates.
• Global aliasing system for cross-file element access.
• Optional dev-mode and strict aliasing for safer development.
• Singleton behavior — every file importing Hepha shares the same instance.

Getting Started

Installation

npm install hephaestus_js

Importing

If you are using a bundler like Vite:

import hepha from "hephaestus_js";

Or via a relative path if not using a bundler:

import hepha from "./hephaestus.js";

Once imported, any element can be created using hepha.relic():

hepha.relic('div'), hepha.relic('span'), hepha.relic('button'), hepha.relic('h1'), ...

Supported HTML Tags

All HTML tags are supported via hepha.relic(tag, options).

div, span, p, button, h1-h6, ul, ol, li,
section, article, header, footer, main,
input, textarea, label, form, a, img,
nav, aside, figure, figcaption,
table, thead, tbody, tr, th, td,
video, audio, source, canvas, svg,
select, option, optgroup, fieldset, legend

Creating Elements

Each element is constructed with an options object:

const btn = hepha.relic('button', {
    text: "Click me",
    class: "btn primary",
    alias: "main_btn",
    events: {
        click: () => console.log("Clicked!")
    },
    style: {
        background_color: "red",
        padding: "10px"
    }
}).into("body");

Options Table

All other keys in options are treated as attributes of the element

Aliases Example

const title = hepha.relic('h1', {
    text: "Welcome!",
    alias: "site_title"
}).into("body");

// Recommended: Access via getter method
hepha.get_alias("site_title").textContent = "Updated!";

Appending Elements with .into()

const card = hepha.relic('div', { class: "card" }).into("#app");

.into() accepts either:

• a CSS selector
• a DOM element

If the selector does not match a node, Hepha throws error 202.

Archetypes

Archetypes define reusable components with deep-merging behavior.

Creating an Archetype

hepha.forge_archetype("card", "div", {
    class: "card",
    style: { padding: "20px" },
    children: [
        hepha.relic('h2', { text: "Title" }),
        hepha.relic('p', { text: "This is a card." })
    ]
});

Using an Archetype

const box = hepha.use_archetype("card", {
    style: { background_color: "black" },
    children: [
        hepha.relic('p', { text: "Extra content!" })
    ]
}).into("body");

How archetypes treat overrides

base     = { style: { color: "red", padding: "10px" } }
override = { style: { padding: "20px" } }

→ result = { style: { color: "red", padding: "20px" } }

Reactivity

Hephaestus provides a simple reactivity system inspired by Vue. You can create reactive state and link it to element properties like text.

1. Initialize State

Use hepha.init_state(initialState, name) or hepha.init_state(initialState) to create a named reactive state object. Access it using hepha.get_state(name).

const state = hepha.init_state({ count: 0 }, 'main');
// Recommendations :
// Creation
const mainState = hepha.init_state({ count : 0}, 'main') // Explicit naming is better, not using one makes it random
// Access
const mainState = hepha.get_state('main');

2. Create a Reactive Reference

Use hepha.ref() to wrap a getter function that accesses your reactive state. When passed to a Hepha element, the element will automatically update whenever the state changes.

// Snapshot: value won't update when state.count changes
hepha.relic('h1', { text: state.count }).into("body");

// Reactive: h1 will automatically update when state.count changes
hepha.relic('h1', { text: hepha.ref(() => state.count) }).into("body");

// Triggering an update:
state.count++; 

Dev Mode

hepha.use_dev();

Logs archetype creation, archetype usage, element creation, and alias overwrites.

Strict Alias Mode

hepha.use_strict_alias();

Prevents alias overwriting (error 301).

Error Codes

Best Practices

• Insist on using getter methods: Always use hepha.get_alias(), hepha.get_state(), and hepha.get_archetype() instead of direct property access.
• Use aliases only for elements that must be accessed globally.
• Use archetypes for repetitive UI patterns.
• Use hepha.init_state() and hepha.ref() for dynamic UI updates.
• Enable dev_mode while developing.
• Remember: all files share the same Hepha instance.
• Use snake_case for styles as Hepha converts it automatically.