docs: update ESBuild setup guide for Alpine.js migration pattern

Browse Source

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.

...

This commit is contained in:

john-okeefe

2026-03-06 22:26:49 -05:00

parent df132c8010

commit 5baef8160e

1 changed files with 1809 additions and 575 deletions

Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL

Download Patch File Download Diff File Expand all files Collapse all files

esbuild-setup.md

+1809 -575

File diff suppressed because it is too large Load Diff