Migration Guide

How to upgrade between xhtmlx versions. Use the CLI tool for automated migration.

Automated Migration

The fastest way to migrate is the built-in CLI tool:

npx xhtmlx-migrate --from=1 --to=2 src/

Preview changes first with --dry-run, or rollback with --reverse.

# Preview changes without modifying files
npx xhtmlx-migrate --dry-run --from=1 --to=2 src/

# Rollback if something breaks
npx xhtmlx-migrate --from=1 --to=2 --reverse src/

# Show all migration rules
npx xhtmlx-migrate --list-rules --from=1 --to=2

v1 → v2

Attribute Renames RENAME

v1 (old)	v2 (new)	Notes
xh-bind	xh-model	Two-way binding renamed for clarity
xh-loading	xh-indicator	Loading indicator renamed to match htmx convention

Value Changes RENAME

Attribute	v1 value	v2 value
xh-swap	"replace"	"outerHTML"

New Requirements BREAKING

Change	Details
xh-ws requires xh-trigger	WebSocket elements now need explicit `xh-trigger="message"`. Previously auto-triggered.
Strict equality for xh-model	Radio buttons and selects use `===` instead of `==`. Ensure data types match option values (e.g. `"1"` not `1`).

New Features in v2 NEW

xh-model — two-way data binding (pre-fill, auto-collect, live reactivity)
xh-class-* — toggle CSS classes based on data
xh-show / xh-hide — toggle visibility
xh-on-* — declarative event handlers
xh-push-url / xh-replace-url — browser history
xh-ws / xh-ws-send — WebSocket support
xh-boost — enhance links and forms
xh-cache — response caching with TTL
xh-retry — automatic retry with backoff
xh-validate — declarative form validation
xh-i18n — internationalization
xh-router / xh-route — SPA routing
xh-focus — focus management after swap
xh-template-mobile / xh-template-tablet — responsive templates
xh-name — named inline templates
Plugin API: xhtmlx.directive(), xhtmlx.hook(), xhtmlx.transform()
UI versioning: xhtmlx.switchVersion()
CSP-safe mode: xhtmlx.config.cspSafe = true

How to Migrate Safely

Run dry-run first — npx xhtmlx-migrate --dry-run --from=1 --to=2 src/
Review the changes — check each file in the output
Commit your current state — so you can revert via git
Apply the migration — npx xhtmlx-migrate --from=1 --to=2 src/
Test your app — run your tests, check the UI
If something breaks — either git revert or npx xhtmlx-migrate --reverse --from=1 --to=2 src/

UI Version Switching

For zero-downtime deployment, use xhtmlx.switchVersion() instead of migrating HTML files:

// Deploy new templates alongside old ones
// /ui/v1/templates/...  (current)
// /ui/v2/templates/...  (new)

// Switch all widgets to v2 templates
xhtmlx.switchVersion("v2");

// Rollback if needed
xhtmlx.switchVersion("v1");

This changes the template prefix at runtime without modifying any HTML files. See switchVersion API docs.