A lightweight, component-based JavaScript framework for building dynamic web applications with minimal boilerplate. Holo.js offers reactive state management, custom component registration, and flexible routing in a simple API.

• Now with DevTools and Error Boundaries!

Contributors

Features

• Reactive State Management: Auto-updating UI based on state changes
• Custom Components: Create reusable web components with simple API
• Template Binding: Easy templating with state variable interpolation
• Flexible Routing: Support for both hash and history routing modes
• Route Guards: Protect routes with custom logic
• Persistent Storage: Simple localStorage API integration
• Minimal Size: Lightweight framework with no dependencies
• Progressive Web App Ready: Built with modern web standards

Installation

• Install it from NPM:

  npm i holo-js

• Use it!

Quick Start

import { Holo, Router } from 'holo-js';

// Initialize the application
const app = Holo.init();

// Set application title
app.setTitle('My Holo App');

// Create state
app.state.counter = 0;
app.state.username = 'Guest';

// Define a component
app.registerComponent({
  name: 'counter-button',
  render: (attrs, inner) => `
    <button onclick="incrementCounter()">
      ${inner || 'Clicks'}: {counter}
    </button>
  `
});

// Global function
app.expose(function incrementCounter() {
  app.state.counter++;
});

// Render the main template
app.render(`
  <div id="app-content"></div>
  <div class="container">
    <h1>{username}'s App</h1>
    <counter-button>Count</counter-button>
  </div>
`);

// Setup router (optional)
const router = new Router({ mode: 'hash' })
  .setHoloInstance(app)
  .setContainer('#app-content')
  .add('/', '<h1>Home</h1><p>Welcome, {username}!</p>')
  .add('/about', '<h1>About</h1><p>This is a Holo app</p>')
  .setNotFoundTemplate('<h1>404</h1><p>Page not found</p>')
  .init();

Core Concepts

Application Instance

The core of every Holo application is an instance created with Holo.init():

const app = Holo.init();

State Management

Holo uses a reactive state system that automatically updates the UI:

// Define state
app.state.count = 0;
app.state.user = { name: 'Guest' };

// Update state (UI updates automatically)
app.state.count++;
app.state.user.name = 'John';

// Subscribe to state changes
app.subscribeToState('count', (newValue, oldValue) => {
  console.log(`Count changed from ${oldValue} to ${newValue}`);
});

Component Registration

Create reusable components with simple registration:

app.registerComponent({
  name: 'user-card',
  render: (attrs, inner) => `
    <div class="card">
      <h3>{user.name}</h3>
      <div class="content">${inner}</div>
      <button onclick="greet('{user.name}')">Say Hello</button>
    </div>
  `
});

// Use the component
app.render(`
  <user-card>This is a user profile</user-card>
`);

Templating

Templates use simple curly brace syntax for state interpolation:

app.render(`
  <div>
    <h1>Welcome, {user.name}!</h1>
    <p>You have {notifications.length} notifications.</p>
  </div>
`);

Routing

The Router provides navigation and content swapping:

const router = new Router({ mode: 'hash' }) // or 'history'
  .setHoloInstance(app)
  .setContainer('#content')
  .add('/', homeTemplate)
  .add('/users', usersTemplate)
  .add('/users/:id', userDetailTemplate)
  .addGuard((from, to) => {
    // Return false to prevent navigation
    // Return string to redirect
    // Return undefined/true to continue
    if (to === '/admin' && !app.state.isAdmin) {
      return '/login';
    }
  })
  .init();

// Navigate programmatically
router.navigate('/users');

Local Storage

Holo includes a simple storage API that is based on localStorage:

// Store data
app.saves.set('user-prefs', { theme: 'dark', fontSize: 16 });

// Retrieve data
const prefs = app.saves.get('user-prefs');

// Remove item
app.saves.rm('user-prefs');

// Clear all app data
app.saves.clear();

API Reference

Holo Class

| Method | Description | |--------|-------------| | Holo.init() | Creates and initializes a new Holo application | | setTitle(title) | Sets the document title | | registerComponent(component) | Registers a custom component | | render(template, targetSelector) | Renders a template to a DOM element | | onReady(callback) | Executes code when DOM is loaded | | expose(fn, name) | Exposes a function globally | | subscribeToState(prop, callback) | Subscribes to state changes |

Router Class

| Method | Description | |--------|-------------| | new Router(options) | Creates a new router instance | | setHoloInstance(app) | Connects router to Holo instance | | setContainer(selector) | Sets the container for route content | | add(path, template) | Adds a route with content template | | setNotFoundTemplate(template) | Sets 404 page template | | addGuard(guardFn) | Adds a navigation guard function | | init() | Initializes the router | | navigate(path) | Navigates to a specific route |

StorageManager Class

| Method | Description | |--------|-------------| | set(key, value) | Stores data in localStorage | | get(key) | Retrieves data from localStorage | | rm(key) | Removes data from localStorage | | clear() | Clears all app data from localStorage |

Best Practices

1. Organize Components: Create components for reusable UI elements
2. State Structure: Keep state organized with logical grouping
3. Event Handling: Use exposed functions for event handling
4. Route Organization: Group related routes for easier maintenance
5. Error Handling: Add error boundaries for component failures

Examples

Todo App

import { Holo } from 'holo-js';

const app = Holo.init().setTitle('Holo Todo');

// Initial state
app.state.todos = [];
app.state.newTodo = '';

// Components
app.registerComponent({
  name: 'todo-item',
  render: (attrs, inner) => `
    <li>
      <input type="checkbox" onclick="toggleTodo(${inner})" 
        ${app.state.todos[inner].done ? 'checked' : ''}>
      <span style="${app.state.todos[inner].done ? 'text-decoration: line-through' : ''}">
        ${app.state.todos[inner].text}
      </span>
      <button onclick="removeTodo(${inner})">×</button>
    </li>
  `
});

// Global functions
app.expose(function addTodo() {
  if (app.state.newTodo.trim()) {
    app.state.todos = [...app.state.todos, { text: app.state.newTodo, done: false }];
    app.state.newTodo = '';
  }
});

app.expose(function removeTodo(index) {
  app.state.todos = app.state.todos.filter((_, i) => i !== index);
});

app.expose(function toggleTodo(index) {
  const newTodos = [...app.state.todos];
  newTodos[index].done = !newTodos[index].done;
  app.state.todos = newTodos;
});

app.expose(function updateInput(e) {
  app.state.newTodo = e.target.value;
});

// Render app
app.render(`
  <div class="todo-app">
    <h1>Holo Todo</h1>
    <div class="add-todo">
      <input type="text" value="{newTodo}" onkeyup="updateInput(event)" 
        onkeypress="if(event.key==='Enter')addTodo()">
      <button onclick="addTodo()">Add</button>
    </div>
    <ul>
      ${'{todos.map((_, i) => `<todo-item>${i}</todo-item>`).join("")}'}
    </ul>
    <div class="info">
      <p>{todos.length} items, {todos.filter(t => t.done).length} completed</p>
    </div>
  </div>
`);

Browser Support

Holo.js supports all modern browser engines that implement the Web Components standard:

• Chromium
• Gecko
• WebKit
• (might support more, but we haven't tested)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GNU General Public License v3.0

see the LICENSE file for details.