Herb: Introduce Herb Dev Server and @herb-tools/client

[marcoroth]

This pull request introduces the Herb Dev Server and the @herb-tools/client package, a WebSocket-based file watching system that enables real-time template hot-reloading during development, heavily inspired by webpack-dev-server and Vite.

Warning

The dev server is experimental and may not work correctly in all cases.

How It Works

The herb dev command starts a WebSocket server that watches template files for changes. When a template is saved, it diffs the old and new Syntax Tree using the Herb diff engine and either:

1. Patches in place for text and attribute changes, the client updates the DOM directly without a page reload
2. Refreshes the page for structural changes (insertions, removals) or ERB changes where in-place patching isn't reliable (yet). We currently only support a very limited set of patches in-place, but this can be expanded to be more feature-complete.

The client connects automatically when herb-debug-mode is enabled in the page and applies patches by matching text content or attribute values within the template's root element ([data-herb-debug-file-relative-path]).

Architecture

Server (lib/herb/dev/server.rb):

• WebSocket server with per-client write mutexes
• Buffered handshake reading with timeout protection
• Per-client version negotiation
• Process registry via ~/.herb/dev-servers/{pid}.json for multi-server coordination

Client (javascript/packages/client/):

• HerbClient message handling, connection lifecycle
• Connection WebSocket management with exponential backoff reconnection
• patch.ts DOM patching via content-based element matching
• ConnectionDot visual connection status indicator
• Toast / MismatchAlert user feedback components

Protocol messages:

• welcome handshake with project path validation
• patch incremental text/attribute updates
• reload structural changes requiring page reload
• error / fixed parse error notifications

Usage

herb dev [directory] [--port 8592]

 🌿 Herb Dev Server

  ⚠️ Experimental: The dev server is experimental and may not work correctly in all cases.

  Herb:      0.9.7
  Project:   /Users/marcoroth/Development/myapp
  Config:    .herb.yml
  Files:     453 templates indexed
  WebSocket: ws://localhost:8592

  Ready! Watching for changes...

The CLI shows whether each change was patched in place (✓ green) or triggered a reload (↻ amber), along with the operation details.

Demo

Tropical.on.Rails.2026.mov

Tropical.on.Rails.20262.mov

[pkg-pr-new]

npx https://pkg.pr.new/@herb-tools/formatter@1662

npx https://pkg.pr.new/@herb-tools/language-server@1662

npx https://pkg.pr.new/@herb-tools/linter@1662

commit: e15379e

[github-actions]

🌿 Interactive Playground and Documentation Preview

A preview deployment has been built for this pull request. Try out the changes live in the interactive playground:

• Playground Preview
• Documentation Preview
• Website Preview

---

_{🌱 Grown from commit e15379e}

---

✅ Preview deployment has been cleaned up.