Merge COLLECTIONS_CLEANUP_GUIDE.md into ALPINE_COMPLETION_GUIDE.md to
create a single, comprehensive migration guide. This consolidates
documentation and reduces redundancy.
Changes:
- Update guide structure from three guides to two guides
- Remove references to COLLECTIONS_CLEANUP_GUIDE.md
- Add Phase 0 (dead export removal) with detailed step-by-step instructions
- Add Phase 3 (DOMContentLoaded cleanup) with file-by-file instructions
- Incorporate detailed fixes for collections.ts, analytics.ts, docs.ts,
dashboard.ts, and library.ts
- Update all cross-references to point to consolidated guide
- Add implementation steps and verification commands
Documentation consolidation rationale:
- Single source of truth for Alpine.js migration
- Eliminates need to reference multiple documents
- Maintains all step-by-step instructions in one place
- Simplifies maintenance and updates
Deleted: COLLECTIONS_CLEANUP_GUIDE.md (content merged into ALPINE_COMPLETION_GUIDE.md)
Updated ALPINE_COMPLETION_GUIDE.md to reference SSR_FIRST_ALPINE_GUIDE.md
and clarify the relationship between all three guides.
Changes:
- Added reference to SSR_FIRST_ALPINE_GUIDE.md as prerequisite
- Added Phase 0: Prerequisites (dead export removal)
- Added Phase 3: Other Templates (DOMContentLoaded cleanup)
- Reorganized Phase numbers (old Phase 3→4, 4→5, 5→6)
- Updated Key Principles section to include SSR-first rules
- Added "How This Guide Relates to Others" section (4.3)
- Updated Next Steps with recommended reading order
- Clarified documentation strategy and goals
Key SSR-first additions:
- ❌ NEVER fetch data in x-init if data is already SSR'd
- ✅ x-init ONLY for setup (event listeners, modals)
- ✅ Data fetch ONLY after user actions (create/delete/update)
Three Guide Strategy:
1. SSR_FIRST_ALPINE_GUIDE.md - Architecture principles (READ FIRST)
2. COLLECTIONS_CLEANUP_GUIDE.md - Quick reference for immediate fixes
3. ALPINE_COMPLETION_GUIDE.md - Full migration path (this guide)
This ensures users understand SSR-first architecture before attempting
full Alpine.js migration, preventing common mistakes like fetching data
in x-init that replaces SSR content.
The guides now work together without contradiction:
- SSR_FIRST establishes principles
- COLLECTIONS_CLEANUP provides quick fix reference
- ALPINE_COMPLETION provides complete migration path
Eventually COLLECTIONS_CLEANUP_GUIDE.md can be deprecated once all patterns
are understood and incorporated into the other two guides.
Created a detailed 1,354-line migration guide to complete the Alpine.js
integration from the current hybrid state (manual DOM manipulation) to
full reactive Alpine.js.
Document contents:
- Current state analysis (121 manual DOM manipulations identified)
- Complete migration strategy with 4-step pattern
- Phase-by-phase implementation guide (header.templ reference + 7 modals)
- Before/after code examples with line numbers
- Alpine.store pattern for global modal state
- Verification checklists and testing procedures
- Troubleshooting guide for common issues
- Success criteria and metrics
Key benefits documented:
- Eliminates 121 instances of manual DOM manipulation
- Reduces header.ts from 100 to 40 lines (60% reduction)
- Adds smooth transitions with x-transition
- Implements click-outside detection with @click.outside
- Provides clean, maintainable architecture
This guide completes the ESBUILD_MIGRATION_PLAN.md Phase 3 (Template
Migration) with actionable steps for any developer to finish the
integration in 10-12 hours.
Related: ESBUILD_MIGRATION_PLAN.md Phase 3, lines 998-1242
john-okeefe