zylix

Zylix

Cross-platform UI framework with a Zig core and JavaScript/WebAssembly bridge.

Features

• Zero-copy state management - All state lives in WASM for performance
• Virtual DOM - Efficient DOM diffing and patching
• Component system - Build UIs with composable components
• TodoMVC ready - Complete todo app implementation included
• TypeScript support - Full type definitions included

Installation

npm install zylix

Quick Start

import { init, state, todo } from 'zylix';

// Initialize WASM module
await init('node_modules/zylix/wasm/zylix.wasm');

// Use state management
state.increment();
console.log(state.getCounter()); // 1

// Use todo API
todo.init();
const id = todo.add('Learn Zylix');
console.log(todo.getCount()); // 1

Modules

Core (zylix/core)

Foundation module for WASM loading and memory management.

import { init, deinit, isInitialized, getMemoryUsed } from 'zylix';

await init('zylix.wasm');
console.log(isInitialized()); // true
console.log(getMemoryUsed()); // Memory usage in bytes

State (zylix/state)

Application state management with events.

import { state } from 'zylix';

// Dispatch events
state.dispatch(state.Events.INCREMENT);

// Convenience methods
state.increment();
state.decrement();
state.reset();

// Get state
console.log(state.getCounter());
console.log(state.getStateVersion());

// Reactive stores
const store = state.createStore({ count: 0 });
const unsubscribe = store.subscribe(value => console.log(value));
store.set({ count: 1 });
unsubscribe();

Todo (zylix/todo)

Complete TodoMVC implementation.

import { todo } from 'zylix';

// Initialize
todo.init();

// CRUD operations
const id = todo.add('Buy groceries');
todo.toggle(id);
todo.updateText(id, 'Buy organic groceries');
todo.remove(id);

// Bulk operations
todo.toggleAll();
todo.clearCompleted();

// Filtering
todo.setFilter(todo.Filter.ACTIVE);
todo.setFilter(todo.Filter.COMPLETED);
todo.setFilter(todo.Filter.ALL);

// Queries
console.log(todo.getCount());
console.log(todo.getActiveCount());
console.log(todo.getCompletedCount());

// Get items
const items = todo.getVisibleItems();
// [{ id: 1, text: 'Learn Zylix', completed: false }]

VDOM (zylix/vdom)

Virtual DOM for efficient UI updates.

import { vdom } from 'zylix';

// Initialize
vdom.init();

// Create nodes
const div = vdom.createElement(vdom.Tag.DIV);
vdom.setClass(div, 'container');

const text = vdom.createText('Hello, Zylix!');
vdom.addChild(div, text);

// Set as root and commit
vdom.setRoot(div);
const patchCount = vdom.commit();

// Apply patches to DOM
const container = document.getElementById('app');
vdom.applyPatches(container);

Component (zylix/component)

Component-based UI building.

import { component } from 'zylix';

// Initialize
component.init();

// Create components
const container = component.createContainer();
const heading = component.createHeading(1, 'Welcome');
const button = component.createButton('Click me');

// Build tree
component.addChild(container, heading);
component.addChild(container, button);

// Add event handlers
component.onClick(button, 1001); // Callback ID

// Render
component.render(container);

Browser Usage

<script type="module">
import { init, state } from './node_modules/zylix/src/index.js';

await init('./node_modules/zylix/wasm/zylix.wasm');

document.getElementById('increment').onclick = () => {
    state.increment();
    document.getElementById('count').textContent = state.getCounter();
};
</script>

Building WASM

If you need to rebuild the WASM module:

# Requires Zig 0.15.0 or later
cd packages/zylix
npm run prepare:wasm

TypeScript

Full TypeScript definitions are included:

import { init, state, todo, vdom, component } from 'zylix';

await init('zylix.wasm');

// All APIs are fully typed
const items: todo.TodoItem[] = todo.getVisibleItems();

API Reference

Core Functions

Function	Description
init(wasmSource, options?)	Initialize WASM module
deinit()	Shutdown WASM module
isInitialized()	Check initialization status
getMemoryUsed()	Get memory usage in bytes
getMemoryPeak()	Get peak memory usage
getAbiVersion()	Get ABI version number

State Functions

Function	Description
dispatch(eventType, payload?)	Dispatch event to core
getCounter()	Get counter value
getStateVersion()	Get state version
increment()	Increment counter
decrement()	Decrement counter
reset()	Reset counter
createStore(initialValue)	Create reactive store

Todo Functions

Function	Description
init()	Initialize todo state
add(text)	Add todo item
remove(id)	Remove todo item
toggle(id)	Toggle completion
toggleAll()	Toggle all items
clearCompleted()	Clear completed items
setFilter(filter)	Set filter mode
getFilter()	Get current filter
getCount()	Get total count
getActiveCount()	Get active count
getCompletedCount()	Get completed count
getVisibleItems()	Get filtered items
getAllItems()	Get all items

Architecture

JavaScript (UI/Events)
        ↓
    zylix.js (Bridge)
        ↓
    zylix.wasm (Zig Core)
        ↓
JavaScript (DOM Updates)

All state management and business logic runs in WASM. JavaScript handles:

• Loading the WASM module
• String encoding/decoding
• DOM manipulation
• Event binding

Requirements

• Modern browser with WebAssembly support
• Node.js 16+ (for build tools)
• Zig 0.15.0+ (for rebuilding WASM)

License

MIT