uihtmx

Wander UI

Modern UI implementation for Wander using HTMX, Templ, and Tailwind CSS.

Directory Structure

ui/
├── handlers/           # HTTP handlers for each route
│                      # Each handler responds with full pages or HTMX partials
│
├── templates/         # Templ templates (*.templ files)
│   ├── layouts/      # Base layouts (main.templ, auth.templ, etc.)
│   ├── components/   # Reusable components (nav, sidebar, cards, etc.)
│   ├── pages/        # Full page templates
│   └── partials/     # HTMX partial response templates
│
├── static/           # Static assets
│   ├── css/         # Tailwind CSS output (output.css - generated)
│   ├── js/          # JavaScript libraries (HTMX, Alpine, CodeMirror)
│   └── icons/       # Heroicons SVG files
│
└── tests/           # Test files
    ├── unit/        # Unit tests for handlers and components
    └── e2e/         # End-to-end tests

Generated Files

The following files are auto-generated and should not be committed:

• templates/**/*_templ.go - Generated by Templ CLI from .templ files
• static/css/output.css - Generated by Tailwind CSS

Development Workflow

1. Write Templ Templates: Create .templ files in the appropriate directory
2. Generate Go Code: Run templ generate to create *_templ.go files
3. Build Handlers: Import and use the generated templates in handlers
4. Style with Tailwind: Use Tailwind utility classes in templates
5. Test: Write unit and e2e tests

Prerequisites

• Go 1.27.3
• Templ CLI: go install github.com/a-h/templ/cmd/templ@v0.3.977
• Air (for hot-reload): go install github.com/air-verse/air@latest
• Node.js 18+ (for Tailwind CSS plugins)

Setup

First Time Setup

You can run setup from the project root or from the ui directory.

From project root:

make ui-setup

From the ui directory:

1. Install Tailwind CSS CLI:

   cd ui
   make install-tailwind
   

   This downloads the standalone Tailwind CLI binary to ./bin/tailwindcss.

2. Install Node Dependencies (for Tailwind plugins):

   npm install
   

   This installs @tailwindcss/forms and @tailwindcss/typography plugins.

3. Build CSS:

   make build-css-dev
   

Or run all setup steps at once:

make setup

Development Workflow

Option 1: Hot-Reload Development (Recommended)

Use air for automatic hot-reload when Go or Templ files change:

From project root:

# Terminal 1: Run development server with hot-reload (watches .go and .templ files)
make ui-dev

# Terminal 2: Watch and rebuild CSS
make ui-css-watch

From the ui directory:

# Terminal 1: Run development server with hot-reload
air

# Terminal 2: Watch and rebuild CSS
make watch-css

The dev server will be available at http://localhost:3000/ui/

Air will automatically:

• Generate Templ templates when .templ files change
• Rebuild the Go server when .go files change
• Restart the server with the new binary

Option 2: Manual Development

If you prefer manual control over the build process:

From project root:

# Terminal 1: Watch and rebuild Templ templates
make ui-watch

# Terminal 2: Watch and rebuild CSS
make ui-css-watch

# Terminal 3: Run the Go server manually
cd ui && go run cmd/dev/main.go

From the ui directory:

# Terminal 1: Watch and rebuild Templ templates
templ generate --watch

# Terminal 2: Watch and rebuild CSS
make watch-css

# Terminal 3: Run the Go server
go run cmd/dev/main.go

Build Commands

Templ Templates

# Generate Templ files once
templ generate

# Watch for changes (development)
templ generate --watch

Tailwind CSS

From project root:

# Development build (not minified)
make ui-css-dev

# Production build (minified)
make ui-css

# Watch for changes
make ui-css-watch

# Complete setup (install + build)
make ui-setup

From the ui directory:

# Development build (not minified)
make build-css-dev

# Production build (minified)
make build-css

# Watch for changes
make watch-css

# Clean generated files
make clean

# Verify configuration
make verify-config

Available Make Targets

Root Makefile targets:

make ui-setup          # Setup UI dependencies (Tailwind CLI + npm packages)
make ui-dev            # Run development server with hot-reload (air)
make ui-css            # Build production CSS (minified)
make ui-css-dev        # Build development CSS (not minified)
make ui-css-watch      # Watch and rebuild CSS on changes
make ui-generate       # Generate Templ templates once
make ui-watch          # Watch and regenerate Templ templates
make ui-fmt            # Format Templ template files

ui/Makefile targets (run from the ui directory):

Run make help from the ui directory to see all available targets:

make help              # Show help
make install-tailwind  # Install Tailwind CSS CLI
make build-css         # Build production CSS (minified)
make build-css-dev     # Build development CSS
make watch-css         # Watch and rebuild on changes
make clean             # Remove generated CSS
make verify-config     # Verify Tailwind config
make check-deps        # Check npm dependencies
make setup             # Complete setup

Hot-Reload Configuration

The .air.toml file configures air for hot-reload development:

• Watched files: .go and .templ files (excluding test files)
• Build command: Runs templ generate then builds the dev server
• Binary location: ./tmp/wander-ui-dev
• Restart delay: 1 second after file changes
• Build logs: Saved to build-errors.log

Air automatically:

1. Detects file changes in Go or Templ files
2. Runs templ generate to update generated Go code
3. Rebuilds the Go binary
4. Restarts the server

This provides a smooth development experience without manual rebuilds.

Development Server

The development server (cmd/dev/main.go) is a lightweight HTTP server that:

• Serves the UI at http://localhost:3000/ui/
• Uses the handlers and router from ui/handlers/
• Supports command-line flags:
  • -port: Server port (default: 3000)
  • -log-level: Logging level (default: info)

Example:

go run cmd/dev/main.go -port 8080 -log-level debug

Architecture Notes

• HTMX: Handles AJAX requests, partial page updates, and progressive enhancement
• Templ: Type-safe Go templates compiled to Go code
• Tailwind CSS: Utility-first CSS framework
• Alpine.js: Minimal JavaScript for interactive components
• CodeMirror: Code editor for HCL/JSON editing

This is the in-progress replacement for the legacy Ember.js UI. Current coverage and remaining work are tracked in docs/plans/ui-feature-status.md.