NodeSculptor šØ
NodeSculptor is a powerful and elegant server-side UI engine for Node.js that enables developers to programmatically build and
compile complete, reactive HTML5 documents. It provides a fluent, chainable API to define the structure, styling, and client-side behavior of web pages, outputting pure, lightweight HTML, scoped CSS, and consolidated JavaScript.
It abstracts away the complexities of direct DOM manipulation and traditional templating, allowing you to construct robust front-end interfaces using a pure JavaScript
name(value) chaining pattern. NodeSculptor automatically handles concerns like ID collisions, performs surgical DOM updates, and simplifies element referencing.
---
š Key Features
*
Fluent API: Every method follows the
name(value) pattern and returns the object for seamless chaining, promoting concise and readable code.
*
Zero-Bundle Reactivity: Features a built-in
Proxy-based state management system that intelligently updates only the necessary parts of the DOM in the browser, without requiring large client-side frameworks or bundles.
*
The Reference System: Easily assign unique nicknames to your elements using
.ref('name') on the server. Access them directly in the browser via
window.UI.get('name'), eliminating the need for manual
document.getElementById calls.
*
Scoped & Global Styling: Utilizes
uniqueClass() to generate collision-proof, dynamically scoped CSS classes during the compilation phase, alongside options for defining global and shared styles.
*
Static Compiler Architecture: Built atop
JSDOM for robust server-side DOM manipulation, NodeSculptor compiles into pure, optimized HTML, CSS, and JavaScript, ideal for fast-loading static sites or efficient server-rendered applications.
---
š¦ Installation
To add NodeSculptor to your project, use npm:
``
bash
`
š” Core Concepts
$3
Sculptor
class is the main entry point and the orchestrator of your web page. It manages the virtual DOM environment, collects all your styling rules, state definitions, and client-side scripts. You instantiate it once per page or compilation unit.
Page Management : Handles the overall HTML document structure (head, body, title, meta tags).
Element Factory : Provides convenient methods (div()
, span()
, h1()
, etc.) to create NodeElement
instances.
Style Definition : Manages global, shared, and unique CSS class definitions.
State Initialization : Defines the initial reactive state for your application.
Compilation : The render()
method is where all elements, styles, and scripts are assembled into the final HTML output.
$3
NodeElement
instance represents a single HTML tag (e.g., , ). It's a wrapper around a JSDOM element that provides a rich, chainable API for configuring its properties, children, styles, and behaviors.
Attribute & Content Control : Set id, text, class, and any custom attribute.
Styling : Apply inline css or assign dynamically generated uniqueClasses.
Hierarchy : Add child elements using child() or append().
Reactivity : Bind element content to reactive state variables using bind().
Interactivity : Attach client-side event listeners (on, click).
Referencing : Create named references (ref) for easy access in browser JavaScript.
š Usage Examples
$3
`javascript
`
$3
only the necessary DOM elements when state changes, ensuring high performance without heavy client-side runtimes.
`javascript
Count is: ${v}).css({ color: '#007bff' }),
State in browser
`
$3
`javascript
`
$3
`javascript
`
š API Reference
$3
constructor() | Initializes a new Sculptor instance with an in-memory JSDOM environment. | None | Sculptor instance | const App = new Sculptor(); |
globalStyle(selector, rules) | Defines CSS rules for a global selector (e.g., 'body', 'h1', '.my-class'). | selector: string (CSS selector)rules: object (CSS properties as camelCase JavaScript object) | this (Sculptor instance) | App.globalStyle('body', { margin: '0', fontFamily: 'sans-serif' }); |
sharedClass(name, rules) | Defines a named CSS class that can be reused across multiple elements. | name: string (Name of the class, without the leading dot)rules: object (CSS properties as camelCase JavaScript object) | this (Sculptor instance) | App.sharedClass('btn-primary', { backgroundColor: 'blue', color: 'white' }); |
defineClass(selector, rules, isRawSelector) | Internal method used by globalStyle and sharedClass to process CSS rules. You generally won't call this directly. | selector: string: object: boolean | this (Sculptor instance) | |
state(key, value) | Initializes a reactive state variable accessible via window.State.key in the browser. Changes to this state will trigger updates to bound elements. | key: string (Name of the state variable)value: any (Initial value of the state variable) | this (Sculptor instance) | App.state('count', 0); |
oncreate(fn) | Registers a function to be executed in the browser once the DOMContentLoaded event fires. Ideal for client-side setup that doesn't rely on specific elements being present. | fn: function (Client-side JavaScript function) | this (Sculptor instance) | App.oncreate(() => console.log('Page loaded!')); |
create(tag) | Factory method to create a new NodeElement instance for a given HTML tag. | tag: string (HTML tag name, e.g., 'div', 'p', 'button') | NodeElement instance | App.create('svg'); |
div() span() ... | Convenience factory methods for common HTML tags, e.g., App.div(), App.p(), App.button(). | None | NodeElement instance | App.div().text('Hello'); |
render(root, config) | Compiles the entire UI into a complete HTML document. | root: NodeElement \| Array \| HTMLElement (The root UI element(s) to be placed in the )config: object (Optional configuration object) | this (Sculptor instance) | App.render(myLayout, { title: 'My Page', meta: [{ name: 'author', content: 'Cline' }] }).output(); |
config.title | (Within config object) Sets the title of the HTML document. | string | | config: { title: 'My Awesome Page' } |
config.meta | (Within config object) Adds tags to the document . Can be a single object or an array of objects, where each object's keys/values are meta tag attributes. | object \| Array | | config: { meta: [{ charset: 'UTF-8' }, { name: 'viewport', content: 'width=device-width, initial-scale=1.0' }] } |
config.scripts | (Within config object) Adds external JavaScript files to the document . Can be a single string URL or an array of URLs. | string \| Array | | config: { scripts: ['/path/to/script.js', 'https://example.com/lib.js'] } |
config.css | (Within config object) Adds external CSS stylesheet files to the document . Can be a single string URL or an array of URLs. | string \| Array | | config: { css: ['/css/style.css', 'https://example.com/theme.css'] } |
config.icon | (Within config object) Sets the favicon for the page. | string (URL to the favicon) | | config: { icon: '/favicon.ico' } |
output() | Returns the last rendered HTML document as a complete HTML string. | None | string (The full HTML document) | const htmlString = App.output(); |
save(path) | Writes the last rendered HTML document to a specified file path on the disk. | path: string (File path including filename, e.g., './public/index.html') | this (Sculptor instance) | App.save('./build/index.html'); |
$3
constructor(tag, engine) | Internal constructor. NodeElement instances are typically created via Sculptor's factory methods (e.g., App.div()). | tag: string: Sculptor instance | NodeElement instance | |
child(tag) | Creates a new NodeElement of the specified tag, appends it as a child to the current element, and returns the new child NodeElement for further chaining. | tag: string | NodeElement instance (the new child) | App.div().child('span').text('Nested Span'); |
id(value) | Sets the id attribute of the element. | value: string | this (NodeElement instance) | App.div().id('my-unique-id'); |
text(value) | Sets the textContent of the element. Escapes HTML. | value: string | this (NodeElement instance) | App.p().text('Hello World!'); |
ref(name) | Assigns a client-side reference name to the element. The element's ID will be stored and accessible in the browser via window.UI.get('name'). If the element doesn't have an ID, a unique one is generated. | name: string | this (NodeElement instance) | App.input().ref('usernameInput'); |
class(value) | Adds one or more CSS class names to the element. | value: string \| Array | this (NodeElement instance) | App.div().class('container').class(['flex', 'centered']); |
attribute(key, value) | Sets a custom HTML attribute on the element. | key: string (Attribute name)value: string (Attribute value) | this (NodeElement instance) | App.img().attribute('src', 'image.jpg').attribute('alt', 'Description'); |
css(styles) | Applies inline CSS styles to the element. | styles: object (CSS properties as camelCase JavaScript object) | this (NodeElement instance) | App.div().css({ backgroundColor: 'red', padding: '10px' }); |
uniqueClass(rules) | Generates a unique, collision-proof CSS class name, defines the rules for it, and applies it to the current element. | rules: object (CSS properties as camelCase JavaScript object) | this (NodeElement instance) | App.button().uniqueClass({ backgroundColor: 'green', color: 'white' }); |
bind(stateKey, templateFn) | Links the element's textContent to a reactive State key. When window.State.stateKey changes in the browser, templateFn is called with the new value, and its result updates the element's text. | stateKey: string (The key in window.State to bind to)templateFn: function (Optional. A client-side function that receives the state value and returns the text to display. Defaults to (val) => val if not provided.) | this (NodeElement instance) | App.h1().bind('username', (name) => Welcome, ${name}!); |
oncreate(fn) | Registers a function to be executed in the browser when this specific element is created and the DOMContentLoaded event fires. | fn: function (Client-side JavaScript function) | this (NodeElement instance) | App.canvas().oncreate((el) => { const ctx = el.getContext('2d'); / ... / }); |
on(event, fn) | Attaches a client-side event listener to the element. | event: string (Event type, e.g., 'click', 'mouseover', 'input')fn: function (Client-side JavaScript function, receives the event object) | this (NodeElement instance) | App.button().on('click', () => alert('Button clicked!')); |
click(fn) | Shorthand for .on('click', fn). Attaches a click event listener. | fn: function (Client-side JavaScript function, receives the event object) | this (NodeElement instance) | App.button().click(() => console.log('Clicked!')); |
append(...children) | Appends one or more children to the current element. Children can be NodeElement instances, raw HTMLElements, or arrays containing these. | children: NodeElement \| HTMLElement \| Array | this (NodeElement instance) | App.div().append(App.p().text('Child 1'), App.span().text('Child 2')); |
š Express.js Integration
compiler , meaning it's designed for optimal performance by generating HTML once on the server. For web applications, you should compile your layouts during server startup and then serve the cached HTML string.
$3
`javascript
Welcome, ${name}!), // Reactive welcome message
`
š Advanced Guide: The Compiler
$3
The Synthesis Phase (Server-Side): NodeSculptor leverages JSDOM to construct a Live DOM Tree in memory. This phase ensures structural integrity and allows for programmatic manipulation of elements, attributes, and styles as if you were working directly in a browser.
The Dehydration Phase ( .render()): During this crucial step, the compiler processes the live DOM tree. CSS properties are converted to kebab-case, the initial reactive State is stringified, and a Surgical Binding Map is created. This map precisely links client-side state variables to specific DOM element IDs that need updating.
The Injection Phase (Final Output): A microscopic, highly optimized client-side runtime is injected into the generated HTML. This runtime includes a Native Proxy that listens for changes to window.State. When a state variable is updated, the Proxy efficiently consults the binding map and updates only the linked DOM IDs, ensuring minimal DOM manipulation and maximum performance.
šØ Examples Gallery
$3
`javascript
Preview: ${v}).css({ fontSize: '1.1em', color: '#333' })
`
$3
`javascript
`
š Recommended Project Structure
`text
`
šļø 1. The Reusable Component ( src/components/Card.js)
Sculptor instance (often named App or UI) and any necessary props, then return a configured NodeElement.
`javascript
`
š 2. The Main Script ( src/main.js)
`javascript
Button Clicked: ${v} times).css({ color: '#28a745' }),
Last interaction: ${v}).css({ color: '#666' }),
Successfully sculpted: ${outPath});
`
š ļø 3. How to Run
Initialize your project:
`bash
`
Install Dependencies:
`bash
`
Run Build Script: If you have src/main.js as shown in the project structure example, run:
`bash
`
public/index.html.
View Your Application: Open the generated public/index.html file in any web browser to see your sculpted page.
$3
package.json. This will automatically re-compile your page whenever you make changes to your source code, allowing for rapid iteration:
`json
``