Comprehensive update to esbuild-setup.md with Alpine.js integration guide
for replacing (window as any) pattern with modern reactive framework.
Key changes:
- Add Alpine.js as recommended approach over vanilla event listeners
- Include Phase 2: TypeScript Alpine registration patterns
- Update Phase 3: Template changes with @click and x-data examples
- Add Phase 5: Step-by-step TypeScript migration with exact line numbers
- Fix toast.ts, api.ts, storage.ts examples to match actual code structure
- Include troubleshooting for Alpine-specific issues
- Add migration checklist and quick reference guide
Architecture decisions:
- Alpine.js for client-side state (modals, dropdowns, theme)
- HTMX for server calls (existing pattern, keep unchanged)
- Hybrid approach: Alpine reactive components + HTMX forms
- Bundle Alpine with ESBuild (~15KB gzipped)
Template updates (27 files):
- Replace onclick="func()" with @click="func()"
- Add x-data for stateful components
- Use x-show/x-transition for modals and dropdowns
- Keep HTMX form submissions unchanged
TypeScript migrations:
- Priority 1: Core utilities (toast.ts, api.ts, storage.ts, events.ts, dom.ts)
- Priority 2: Stateful components (header.ts themeDropdown, woodPaneling.ts)
- Priority 3: Page-specific functions (collections.ts, devices.ts, etc.)
- Register functions with Alpine.global() or Alpine.data()
Testing and verification:
- Alpine DevTools for debugging reactive state
- Build step: esbuild --run scripts/build-docs-search.ts
- Verify no 404 errors for missing .js files
- Test all 151 onclick handlers work with @click
Bundle size: ~130KB minified (~40KB gzipped) with Alpine included
Browser support: ES2020 (Chrome 80+, Firefox 72+, Safari 13.1+)
Document is now 1,812 lines with comprehensive step-by-step instructions
for migrating from (window as any) exports to Alpine.js components.
Replace the postinstall script that downloaded minified JavaScript libraries
(htmx, highlight.js, lunr) with proper npm package management and bundling
using esbuild. This provides better dependency management, smaller bundle sizes
through tree-shaking, and improved build times.
Changes:
- Add htmx.org, highlight.js, lunr, and alpinejs as npm dependencies
- Replace tsc with esbuild for faster TypeScript compilation and bundling
- Add esbuild to devDependencies
- Update build:ts script to use esbuild with bundling and minification
- Add build:ts:dev script for development builds without minification
- Add build:ts:watch script for watch mode development
- Remove postinstall script that downloaded external JS files
- Add esbuild-setup.md documentation for the new build setup
- Create web/src/main.ts as the new entry point for bundled JavaScript
This modernizes the frontend build pipeline and reduces reliance on external
CDNs during the build process.
john-okeefe