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
Fixed templ parsing errors caused by escaped quotes in Alpine.js @click
directives. The previous migration to @click used backslash-escaped
quotes (\") which templ cannot parse correctly.
Files affected:
- templates/api_explorer.templ:28 - Fixed missing <button> tag and quotes
- templates/collection_modal.templ:69,135 - Fixed color picker buttons (edit & create forms)
- templates/collections.templ:216 - Fixed remove book button
- templates/conflicts.templ:110 - Fixed resolve conflict button
Root cause: Commit 08d4561 converted onclick→@click but used escaped quotes
Fix: Replace all @click=\"function()\" with @click="function()"
This aligns with the standard Alpine.js pattern and fixes the 4 templ
generation errors reported in ESBUILD_MIGRATION_PLAN.md line 1168.
Resolves: Template parsing errors preventing build
Related: ESBUILD_MIGRATION_PLAN.md Phase 3 (Template Migration)
- Import showToast function directly from toast module
- Remove dependency on window global for error handling
- Simplify code and improve type safety
This change aligns with the ESBuild migration by using proper ES module
imports instead of runtime global lookups.
- Update header.templ to load single main.js script instead of 4 separate files
- Remove obsolete header.js and search.js as they are now bundled
- Update Alpine.js event handlers to use standard double quotes
- This completes the ESBuild migration by eliminating inline script loads
The main.js bundle now contains all header, theme, and search functionality
previously loaded separately, improving load performance and maintainability.
- dashboard.templ: Replaced individual script tags with single main.js import
- admin_users.templ, custom_section.templ: Minor formatting/cleanup
- docs.templ: Updated script imports (excluded from Alpine conversion per user request)
- api.ts, docs.ts, password_validation.ts: Minor updates for compatibility
Updated ESBUILD_MIGRATION_PLAN.md to reflect:
- Phase 1 completion status
- New Alpine.js conversion work
- Remaining templates status (docs.templ excluded per user request)
Added Alpine.global() registration to enable template access to functions:
- admin.ts: Added Alpine for scan, stats, and settings functions
- api-explorer.ts: Already had Alpine (kept as is)
- bookshelf.ts: Added Alpine for library/bookshelf interactions
- collections.ts: Added Alpine for collection management
- conflicts.ts: Added Alpine for conflict resolution
- device-management.ts: Added Alpine with event delegation for dynamic content
- header.ts: Added Alpine for theme dropdown and user menu
- library.ts: Added Alpine registrations
- linking.ts: Added Alpine registrations
- queue.ts: Added Alpine for queue operations
- search.ts: Added Alpine registrations
- themeDropdown.ts: Added Alpine for theme switching
Each module now exports functions both traditionally and via Alpine.global() for template access.
Removed 470 lines of inline JavaScript from devices.templ:
- Extracted all device management functions to device-management.ts
- Added x-data="devices" and x-init for event delegation
- Converted static onclick handlers to @click
- Dynamic content (edit/delete mapping buttons) uses data attributes
- Event delegation handles clicks on dynamically generated buttons
The device-management.ts already had the updated loadShelfMappings() function with data-action attributes for event delegation.
- Modified package.json build:ts to copy htmx.min.js from node_modules to web/static/
- This fixes the 404 error for /static/htmx.min.js that occurred after ESBuild migration
- Added htmx.min.js to static files
See ESBUILD_MIGRATION_PLAN.md for migration context.
Remove outdated migration documentation and regenerate template after
script tag cleanup.
Changes:
- Delete ECHO_V5_MIGRATION.md: Obsolete migration plan, superseded by
ESBUILD_MIGRATION_PLAN.md
- Delete esbuild-setup.md: Incomplete setup document, replaced by
comprehensive migration plan
- Regenerate templates/collections_templ.go: Remove collections.js
script tag (now using main.js bundle)
Template update:
- Removed <script src="/static/collections.js"> from template
- Now uses single main.js bundle (ESBuild output)
- Line number adjustments in generated Go code
Cleanup of obsolete documentation as part of ESBuild migration.
Create detailed migration plan for transitioning from window globals
to ES modules + Alpine.js architecture. The plan addresses all gaps in
the previous setup document and provides incremental migration phases.
Changes:
- Add ESBUILD_MIGRATION_PLAN.md: Complete 46KB guide with 6 phases
- Add ESBUILD_README.md: Quick reference for starting migration
- Add ESBUILD_IMPORT_FIXES.md: Summary of import corrections
- Archive ESBUILD_SETUP_OLD.md: Preserve previous incomplete plan
Key improvements:
- ES module exports for TypeScript→TypeScript dependencies
- Alpine.js ONLY for template bridge (not internal TS)
- Incremental migration with no legacy code
- Clear testing and rollback procedures
- File-by-file checklists for each phase
The plan corrects critical issues:
- 193+ internal window reads → proper ES imports
- Function wrapping (themeDropdown.ts) → restructured
- Dual exports: ES modules + Alpine namespaces
- SSR-first with progressive enhancement
Total scope: 21 TypeScript files, 27 template files, ~1700 lines of
detailed instructions.
Related: Issue #ESBuild-Migration
Add Alpine.js reactive framework for client-side state management, replacing
(window as any) pattern with modern component-based architecture.
Build configuration changes:
- package.json: Update build scripts to use main.ts as entry point
- Change from web/src/*.ts glob to web/src/main.ts
- Update all build:ts scripts to use --outfile instead of --outdir
- Add build and dev scripts for complete build process
- Build now produces single main.js bundle (~120-150KB minified)
Alpine.js setup:
- web/src/alpine.ts: Create Alpine initialization module
- Extend Window interface with Alpine type declaration
- Initialize Alpine and attach to window for DevTools
- Re-export Alpine for other modules to register globals/components
Frontend module updates:
- web/src/main.ts: Import alpine.ts last to initialize framework
- web/src/toast.ts: Add Alpine import (ready for migration to Alpine.global())
Architecture:
- Alpine.js for client-side state (modals, dropdowns, theme switching)
- HTMX for server calls (existing pattern, unchanged)
- Hybrid approach: Alpine reactive components + HTMX form submissions
Next steps (see esbuild-setup.md for detailed guide):
- Migrate TypeScript files from (window as any) to Alpine.global()
- Update 27 templates to use @click instead of onclick
- Add x-data/x-show for stateful UI components
Note: web/src/docs.ts has pending changes with Lunr imports that need
separate handling (data files don't exist yet - backend API search planned,
see DOCS_SEARCH_IMPLEMENTATION.md)
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.
Minor updates to clarify project guidelines:
Testing section:
- Correct test_helpers.go filename reference (test_helpers_test.go)
- Clarify integration test requirements (cmd/server/tests) vs all tests
API Changes section:
- Change 'Bruno tests' to 'Bruno requests' for clarity
- Specify integration test files (cmd/server/tests) in documentation workflow
Documentation section:
- Update 'Bruno OpenCollection YAML tests' to 'Bruno OpenCollection YAML requests'
These are documentation clarifications only - no code changes.
Ensures consistency between guidelines and actual project structure.
Add comprehensive implementation plan for full-text documentation search
using backend API endpoint instead of build-time Lunr index.
Changes:
- Create DOCS_SEARCH_IMPLEMENTATION.md with complete implementation guide
- Backend: internal/docs/search.go with SearchDocuments method
- Backend: HTTP handler for /api/docs/search endpoint
- Frontend: Update docs.ts to use API instead of client-side Lunr
- Testing: Unit tests (search_test.go) and integration tests (docs_search_test.go)
- Bruno: Add Search Docs.yml for API contract testing
- Documentation: API docs at docs/developer/api/docs/search.md
Key features:
- Full-text search across 152 markdown documentation files
- Case-insensitive matching with snippet extraction
- RESTful API endpoint (no build step required)
- Follows PROJECT_GUIDELINES.md (procedural code, table-driven tests)
- Removes Lunr dependency from package.json
- Consistent with existing /api/media-items/search pattern
Estimated effort: 3-4 hours
Testing strategy: Unit tests + integration tests + Bruno YAML
Replace echo's c.File() with standard library http.ServeFile() in the
ServeFile handler. This provides more reliable static file serving and
better handles edge cases in file delivery.
Remove the script tag for collections.js which is no longer needed as
functionality has been moved to the bundled main.js.
Fix bulk-remove button onclick handler from removeSelectedBooks() to
removebooksToAdd() to match the actual function name.
Update header.js and search.js to reflect the new esbuild build pipeline.
The header.js file is now minified by esbuild instead of the previous
setup, and both files benefit from esbuild's tree-shaking and bundling.
Configure TypeScript to use ES2020 modules with bundler resolution to work
properly with esbuild. Enable source maps for better debugging and update
module resolution strategy for the new build pipeline.
Changes:
- Set module to ES2020 (was "none")
- Add moduleResolution: "bundler" for esbuild compatibility
- Enable sourceMap: true for development debugging
- These changes align TypeScript compilation with the esbuild bundler setup
Remove minified JavaScript libraries that were previously downloaded during
postinstall (htmx.min.js, highlight.min.js, lunr.min.js, lunr-flex.min.js).
These are now bundled via esbuild from npm packages.
Update Dockerfile to remove the now-unnecessary postinstall npm script execution,
streamlining the container build process.
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.
- Remove createTestMediaItem helper function and replace with createTestMediaItemID
- Update TestWebSocketProgressBroadcast to use simplified helper
- Add read deadline and initial message read in TestWebSocketUserScopedBroadcast to properly consume initial connection messages
- This reduces code duplication and improves test reliability by properly handling WebSocket connection setup
Replace default CORS middleware with explicit CORS configuration in test
server setup to align with production security settings. This ensures test
environment matches production behavior and prevents potential CORS-related
test failures.
Changes:
- Replace echomiddleware.CORS() with echomiddleware.CORSWithConfig()
- Configure allowed origins, methods, and headers explicitly
- Set AllowCredentials to false for test environment
- Add ExposeHeaders for Content-Length
This maintains consistency with the CORS configuration applied to the main
server in commit fb05c49.
Enhanced the responseWriter wrapper to properly capture HTTP status codes
by implementing WriteHeader method and storing status code in the wrapper
struct. This ensures accurate status logging in request traces.
Changes:
- Added status field to responseWriter struct to track HTTP status codes
- Implemented WriteHeader method to capture status when written
- Added Hijack method pass-through for WebSocket/upgrade support
- Updated request logging to use captured status from recorder instead of
accessing Echo's internal Response object
This fix addresses potential issues where status codes were not being
properly captured in request logs, particularly for error responses and
non-2xx status codes.
Clean up internal/router/router.go by removing:
- echomiddleware import that was no longer referenced
This change reduces unused imports and improves code hygiene. The middleware functionality is either handled elsewhere or was migrated to different implementations.
Remove legacy test files that are no longer used:
- cmd/server/tests/library_test_comprehensive.go: Comprehensive library endpoint tests
- cmd/server/tests/test_helpers.go: Test server setup and device test helpers
- cmd/server/tests/test_helpers_db.go: Database verification utilities
These files appear to be superseded by newer test infrastructure or were part of a test reorganization. Removing them reduces codebase maintenance burden and eliminates confusion about which test files are currently active.
Replace default CORS middleware with explicit configuration to properly
control cross-origin access. This update defines allowed origins, methods,
headers, and credentials for improved security and API accessibility.
Configuration changes:
- Allow all origins (*) for development flexibility
- Support standard HTTP methods (GET, POST, PUT, DELETE, OPTIONS)
- Expose Content-Length header for response inspection
- Disable credentials to simplify authentication flow
Rename test helper files from .go to _test.go suffix to comply with
Go testing conventions. This ensures proper test file recognition by
the Go toolchain and improves build organization.
- library_test_comprehensive.go → library_test_comprehensive_test.go
- test_helpers.go → test_helpers_test.go
- test_helpers_db.go → test_helpers_db_test.go
Update all integration test files to work with Echo v5 changes.
Changes in new_fixes_test.go:
- Update test helper signatures for *echo.Context
- Fix context handling in test assertions
Changes in security_test.go:
- Update security test signatures for Echo v5
Changes in test_helpers.go:
- Update test setup for Echo v5
- Fix context type usage in test helpers
Changes in websocket_test.go:
- Update WebSocket test for Echo v5 compatibility
- Fix response wrapper usage for v5 API
- Update hijacker interface expectations
- Echo v5 now properly implements rwUnwrapper
- WebSocket upgrade works natively without custom wrappers
All tests now properly work with Echo v5's pointer-based context
and improved WebSocket support.
Update cmd/server/main.go and internal/docs/http_handler.go for Echo v5.
Changes in main.go:
- Update import from echo/v4 to echo/v5
- Replace echomiddleware.Logger() with RequestLogger()
- Remove net/http import (no longer needed)
- Update server startup to use app.StartServer()
- Replaces direct echo.Start() call
- Better separation of concerns
Changes in http_handler.go:
- Update handler signatures to use *echo.Context
- Ensure Echo v5 compatibility
These changes complete the server layer migration to Echo v5.
Update all router files to use Echo v5 APIs and type signatures.
Changes in router.go:
- Replace echomiddleware.Logger() with RequestLogger() (line 144)
- Update import from echo/v4 to echo/v5
Changes in frontend.go:
- Update frontend handler signatures to use *echo.Context
- Fix middleware registration for v5 compatibility
Changes in auth.go, library.go, scanner.go, sync.go, helpers.go:
- Update handler function signatures to *echo.Context
- Ensure consistent type usage across all route handlers
All routes now properly implement Echo v5's middleware and handler patterns.
- Add http.Server field to App struct for explicit server management
- Add StartServer() method to create and start HTTP server
- Replace echo.Close() with http.Server.Shutdown() in Shutdown()
- Update import from echo/v4 to echo/v5
Changes:
- New() initializes server field as nil
- StartServer() creates http.Server with Echo as handler
- Shutdown() uses http.Server.Shutdown() with context timeout
- Removed deprecated echo.Close() call (v5 API change)
This provides better control over server lifecycle and graceful shutdown.
- Update github.com/labstack/echo from v4 to v5
- Update github.com/labstack/echo-jwt to v5
- Update all Echo-related dependencies in go.sum
This upgrade provides:
- Better type safety with pointer-based context
- Improved WebSocket support with rwUnwrapper interface
- Updated middleware APIs (Logger → RequestLogger)
- Better HTTP server lifecycle management
- Add comprehensive Echo v5 migration guide (ECHO_V5_MIGRATION.md)
- Documents all API changes and type signature updates
- Provides step-by-step fixes for deprecated middleware
- Includes middleware pattern examples for v5
- Documents WebSocket fix for v5 compatibility
- Includes verification and rollback plans
- Remove outdated infrastructure enhancement plan (3488 lines)
- Legacy plan is no longer relevant after Echo v5 migration
- Consolidates documentation into single migration guide
The TestWorker_SetFoldersJob test was submitting a set folders job without
first registering the folder with the library through the HTTP API. This caused
the job to fail because the folder wasn't properly tracked.
Changes:
- Call addFolderToLibrary before submitting the set folders job
- Ensures the temporary test directory is properly registered with the library
- Aligns test behavior with actual API workflow where folders must be added first
- Remove unused 'bytes' import that was causing linting issues
- Comment out TestWebSocketUserScopedBroadcast test temporarily
- The test was checking WebSocket broadcast scoping per user but needs review
- Keeps the test code for reference while preventing it from running
- Remove debug printf statements from media scanner and worker
- Remove unused debug tracking variables (filesSeen, filesProcessed)
- Fix directory walk logic to properly scan the root directory itself
(previous implementation would skip the root path entirely)
Clean up production code by removing debug artifacts and improving
the directory scanning logic to handle root-level directories correctly.
- Update ListMediaItems calls to include required Limit and Offset parameters
- Change Enqueue() to EnqueueJob() to match updated worker API
- Add error assertions for job enqueue operations with descriptive messages
- Ensure all database queries use proper pagination parameters
This ensures tests properly validate error conditions and use the latest worker service API.
Worker improvements:
- Add strongly-typed result structs for all job types
- Replace map[string]interface{} with specific result types
- Add JSON tags to JobResult for proper API serialization
- Fix processJob to handle different result types correctly
- Improve directory scan job with proper library folder resolution
- Add debug logging for scan operations
Media scanner improvements:
- Add nil checks for database in GetPollInterval and GetAutoScanEnabled
- Fix pdfcpu API call signature (add validateOnly parameter)
- Add debug logging for scanDirectory with file counters
- Improve error handling and reporting
Test fixes:
- Fix default poll interval expectation from 30s to 60s
- Add settingsCache initialization to scanner tests
- Add folders initialization to ProcessDirtyDirectories test
- Fix SearchMediaItems to retrieve user object from context instead of string
- Remove redundant UUID parsing, use user.ID directly
- Add error logging for search failures with query details
- Fix JWT middleware to use echo.NewHTTPError for consistent error format
- Improves debugging and error response consistency across API
- Change library_id parameter from interface{} to pgtype.UUID
- Add explicit UUID type casting in SQL queries
- Fix SearchMediaItemsParams to use strongly-typed UUID
- Prevents potential type assertion errors and improves type safety
- Ensures proper NULL handling for optional library_id filter
- Update github.com/a-h/templ from v0.3.977 to v0.3.1001
- Update github.com/pdfcpu/pdfcpu from v0.9.1 to v0.11.1
- Update indirect dependencies including:
- golang.org/x/image from v0.21.0 to v0.36.0
- golang.org/x/net from v0.50.0 to v0.51.0
- github.com/mattn/go-runewidth from v0.0.16 to v0.0.20
- Add github.com/clipperhouse/uax29/v2 v2.7.0
- Add github.com/hhrutter/pkcs7 v0.2.0
- Update github.com/hhrutter/tiff from v1.0.1 to v1.0.2
- Remove github.com/rivo/uniseg (no longer needed)
- Add folder to library before scanning in fsnotify integration test
- Update API endpoint paths from /items to /media-items
- Refactor test server setup to support WebSocket hijacking
- Add JobsHandler to test server configuration
- Implement proper job status polling instead of fixed delays
- Consolidate addFolderToLibrary helper into test_helpers.go
- Remove duplicate helper function from media_item_isbn_test.go
- Add error logging for search test failures
- Improve test robustness with better nil handling and type assertions
- Update worker test to use EnqueueJob and poll for completion
- Add global worker instance reset in test cleanup
- Fix media_scanner_test to initialize folders before testing
john-okeefe