@livetemplate/client
v0.7.7
Published
TypeScript client for LiveTemplate tree-based updates
Maintainers
adnaanxReadme
@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
- Tree-based Updates: Efficiently applies minimal JSON updates to the DOM
- Static Structure Caching: Client caches static HTML, receives only dynamic changes
- DOM Morphing: Uses morphdom for efficient, minimal DOM updates
- WebSocket Transport: Real-time bidirectional communication
- Focus Management: Preserves focus during updates
- Form Lifecycle: Automatic form state management
- Event Delegation: Efficient event handling
- Modal Management: Built-in modal support
- TypeScript: Full type safety and IDE support
Installation
npm
npm install @livetemplate/clientCDN
<script src="https://cdn.jsdelivr.net/npm/@livetemplate/[email protected]/dist/livetemplate-client.browser.js"></script>Quick Start
Browser (via CDN)
<!DOCTYPE html>
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/@livetemplate/[email protected]/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): voidEvents
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);
});How It Works
- Initial Render: Client fetches full HTML from server, caches static structure
- Updates: Server sends only changed dynamic values as tree updates
- DOM Morphing: Client applies updates using morphdom for minimal DOM changes
- 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 buildProject 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 suiteRunning Tests
# Run all tests
npm test
# Run specific test
npm test -- focus-manager
# Run with coverage
npm test -- --coverageBuilding
# Build TypeScript and browser bundle
npm run build
# Build browser bundle only
npm run build:browser
# Clean build artifacts
npm run cleanRelated Projects
- LiveTemplate Core - Go library for server-side rendering
- LVT CLI - Code generator and development server
- Examples - Example applications
Version Synchronization
This client library follows the LiveTemplate core library's major.minor version. For example:
- Core:
v0.1.5→ Client:v0.1.x(any patch version) - Core:
v0.2.0→ Client:v0.2.0(must match major.minor)
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
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: LiveTemplate Docs