@livetemplate/client

TypeScript/JavaScript client library for LiveTemplate - reactive HTML over the wire.

Overview

The LiveTemplate client enables reactive web applications by efficiently applying tree-based HTML updates from the server. It uses DOM morphing, intelligent static content caching, and WebSocket transport for real-time interactivity.

Features

Installation

npm

npm install @livetemplate/client

CDN

<script src="https://cdn.jsdelivr.net/npm/@livetemplate/client@0.1.0/dist/livetemplate-client.browser.js"></script>

Quick Start

Browser (via CDN)

<!DOCTYPE html>
<html>
<head>
    <script src="https://cdn.jsdelivr.net/npm/@livetemplate/client@0.1.0/dist/livetemplate-client.browser.js"></script>
</head>
<body>
    <div id="app"></div>
    <script>
        const client = new LiveTemplateClient.LiveTemplateClient({
            targetSelector: "#app",
            wsUrl: "ws://localhost:8080/ws",
            httpUrl: "http://localhost:8080"
        });

        client.connect();
    </script>
</body>
</html>

TypeScript/ES Modules

import { LiveTemplateClient } from "@livetemplate/client";

const client = new LiveTemplateClient({
    targetSelector: "#app",
    wsUrl: "ws://localhost:8080/ws",
    httpUrl: "http://localhost:8080"
});

client.connect();

Configuration Options

interface LiveTemplateClientOptions {
    // Required
    targetSelector: string;      // CSS selector for target element
    wsUrl: string;                // WebSocket URL
    httpUrl: string;              // HTTP URL for initial render

    // Optional
    debug?: boolean;              // Enable debug logging (default: false)
    reconnectInterval?: number;   // Reconnect interval in ms (default: 3000)
    maxReconnectAttempts?: number;// Max reconnect attempts (default: 10)
}

API

Client Methods

// Connect to server
client.connect(): void

// Disconnect from server
client.disconnect(): void

// Send event to server
client.sendEvent(event: string, data: any): void

// Set debug mode
client.setDebug(enabled: boolean): void

Events

The client emits events you can listen to:

// Connection established
window.addEventListener("livetemplate:connected", (e) => {
    console.log("Connected to server");
});

// Connection closed
window.addEventListener("livetemplate:disconnected", (e) => {
    console.log("Disconnected from server");
});

// Update received
window.addEventListener("livetemplate:update", (e) => {
    console.log("Received update:", e.detail);
});

Drag-and-drop notes

The client supports six native HTML5 drag events as lvt-on:* bindings: dragstart, dragover, drop, dragend, dragenter, dragleave. On drop, the action message includes dragSourceKey (the dragged item's data-key) and dragTargetKey (the drop target's data-key).

How It Works

  1. Initial Render: Client fetches full HTML from server, caches static structure
  2. Updates: Server sends only changed dynamic values as tree updates
  3. DOM Morphing: Client applies updates using morphdom for minimal DOM changes
  4. Caching: Static HTML structure is cached, never re-transmitted

This results in ~75% reduction in update payload sizes compared to full HTML updates.

Development

Setup

# Clone repository
git clone https://github.com/livetemplate/client.git
cd client

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

Project Structure

client/
├── livetemplate-client.ts       # Main client
├── dom/                         # DOM utilities
│   ├── directives.ts
│   ├── event-delegation.ts
│   ├── focus-manager.ts
│   ├── form-disabler.ts
│   ├── loading-indicator.ts
│   ├── modal-manager.ts
│   └── observer-manager.ts
├── state/                       # State management
│   ├── form-lifecycle-manager.ts
│   └── tree-renderer.ts
├── transport/                   # Network layer
│   └── websocket.ts
├── utils/                       # Utilities
│   ├── logger.ts
│   ├── rate-limit.ts
│   └── testing.ts
└── tests/                       # Test suite

Running Tests

# Run all tests
npm test

# Run specific test
npm test -- focus-manager

# Run with coverage
npm test -- --coverage

Building

# Build TypeScript and browser bundle
npm run build

# Build browser bundle only
npm run build:browser

# Clean build artifacts
npm run clean

Version Synchronization

This client library follows the LiveTemplate core library's major.minor version. For example:

Patch versions are independent and can be incremented for client-specific fixes.

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE for details.

Support

Edit this page on GitHub