Files

T

john-okeefe e20857d760 docs: Create comprehensive ESBuild migration plan

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

2026-03-08 01:14:07 -05:00

2.7 KiB

Raw Blame History

Import Fixes Applied to Migration Plan

Summary

All imports in the ESBUILD_MIGRATION_PLAN.md have been corrected to use individual function imports instead of namespace objects, matching your actual module exports.

Changes Made

1. TypeScript Imports (Phase 1)

Changed from namespace imports to individual function imports:

Before (WRONG):

import { api } from "./api";
import { dom } from "./dom";
import { events } from "./events";

After (CORRECT):

import { apiGet, apiPost, apiPut, apiDelete, apiPatch, handleResponse, handleVoidResponse, handleError } from "./api";
import { querySelector, querySelectorAll, getElementById, createElement, ... } from "./dom";
import { onDelegatedClick, onDelegatedSubmit, onDelegatedChange, ... } from "./events";

2. Function Calls in TypeScript

Changed from namespaced calls to direct function calls:

Before (WRONG):

const response = await api.get("/libraries");
showToast.success("Loaded!");
const el = dom.getElementById("id");

After (CORRECT):

const response = await apiGet("/libraries");
showToast("Loaded!", "success");
const el = getElementById("id");

3. Alpine/Template Calls (Phase 3)

Keep namespace objects (Alpine creates these):

CORRECT for Templates:

<button @click="api.post('/api/save', data)">Save</button>
<button @click="showToast.success('Saved!')">Save</button>

Key Distinction

TypeScript Code

Imports: Individual functions
Calls: Direct function calls with arguments
Example: import { apiGet } → apiGet("/url")

Template/Alpine Code

Imports: None (Alpine handles this)
Calls: Namespaced via Alpine.global()
Example: @click="api.post()" (Alpine namespace)

Files Affected

All TypeScript file examples in Phase 1 now show correct imports:

✅ dashboard.ts
✅ analytics.ts
✅ library.ts
✅ collections.ts
✅ bookshelf.ts
✅ api-explorer.ts
✅ All others

Verification

# Verify no namespace imports remain in TypeScript sections
grep "import { api } from\|import { dom } from\|import { events } from" ESBUILD_MIGRATION_PLAN.md | grep -v "//" | wc -l
# Result: 0 ✅

# Verify Alpine namespace calls in templates
grep '@click="api\.' ESBUILD_MIGRATION_PLAN.md | wc -l
# Result: 3 ✅

# Verify TypeScript individual imports
grep "import { apiGet" ESBUILD_MIGRATION_PLAN.md | wc -l
# Result: 9 ✅

Plan Status

✅ Ready to execute - All imports corrected ✅ Consistent throughout - TypeScript vs Alpine distinction clear ✅ Matches your actual exports - No namespace objects exported from modules

You can now start Phase 0 with confidence!

2.7 KiB Raw Blame History