bookhoard/ESBUILD_README.md

# ESBuild Migration - Quick Reference

## Status: Ready to Execute

**Created**: Complete migration plan (ESBUILD_MIGRATION_PLAN.md)
**Archived**: Old incomplete plan (ESBUILD_SETUP_OLD.md)

## The Problem

- **274 window global references** across 21 TypeScript files
- **193+ internal TypeScript dependencies** using window instead of ES imports
- **27 template files** with 150+ unique onclick handlers
- **Function wrapping** creating tight coupling
- **Individual .js files** instead of single bundle

## The Solution

**Incremental migration** with no legacy code:

1. **Phase 0**: Add ES exports (1-2 hours) - Can ship ✅
2. **Phase 1**: Convert internal dependencies (4-6 hours) - Can ship ✅
3. **Phase 2**: Alpine.js bridge (2-3 hours) - Can ship ✅
4. **Phase 3**: Template migration (27-54 hours) - Can ship per template ✅
5. **Phase 4**: Data injection (1-2 hours) - Can ship ✅
6. **Phase 5**: Cleanup (1-2 hours) - Final step

**Total**: 36-69 hours over ~5 weeks

## Key Architecture Decisions

### 1. ES Modules for TypeScript → TypeScript
```typescript
// library.ts
import { api } from "./api";
import { showToast } from "./toast";

const response = await api.get("/libraries");
showToast.success("Loaded!");
```

### 2. Alpine.js for Templates → TypeScript ONLY
```typescript
// api.ts (bottom of file)
import { Alpine } from "./alpine";

Alpine.global("api", {
  get: apiGet,
  post: apiPost,
  // ...
});
```

```html
<!-- template -->
<button @click="api.post('/api/save', data)">Save</button>
```

### 3. SSR-First with Progressive Enhancement
- Server renders complete HTML with data
- Client-side JavaScript only for interactivity
- Data loaded via fetch() APIs
- No window globals for data

## File Changes

### 21 TypeScript Files
All will have:
- ES module exports (`export { functions }`)
- ES module imports (`import { functions } from "./module"`)
- Alpine registration (`Alpine.global("namespace", { ... })`)
- NO window exports (cleaned up in Phase 5)

### 27 Template Files
All will have:
- Single script tag: `<script src="/static/main.js"></script>`
- Alpine directives: `@click` instead of `onclick`
- Alpine state: `x-data` for modals/dropdowns
- NO individual .js file loads

## Quick Start

### Right Now: Start Phase 0

```bash
# 1. Open web/src/api.ts
# 2. Add at bottom (after Alpine.global block):
export { apiGet, apiPost, apiPut, apiDelete, apiPatch, handleResponse, handleVoidResponse, handleError };

# 3. Repeat for other utility modules (toast.ts, events.ts, theme.ts, header.ts, woodPaneling.ts)

# 4. Build and test
npm run build:ts
go run .
```

### After Phase 0 Complete

Move to Phase 1: Convert internal dependencies (see full plan)

## Critical Path

**Must complete in order**:
1. Phase 0 (ES exports) - Enables Phase 1
2. Phase 1 (Internal imports) - Enables Phase 2
3. Phase 2 (Alpine registration) - Enables Phase 3
4. Phase 3 (Template migration) - Can do incrementally
5. Phase 4 (Data injection) - Verify pattern
6. Phase 5 (Cleanup) - Final polish

## Safety Features

✅ **Incremental**: Each phase is complete and testable
✅ **Ship anytime**: Can deploy after Phases 0-2, or during Phase 3
✅ **Easy rollback**: Revert individual files if issues
✅ **No legacy**: Each file fully migrated, no half-states
✅ **Testing**: Clear verification criteria for each phase

## Common Patterns

### Before Migration
```typescript
// TypeScript
function doWork() { ... }
(window as any).doWork = doWork;

// Another file
const result = (window as any).doWork();
```

```html
<!-- Template -->
<button onclick="doWork()">Click</button>
```

### After Migration
```typescript
// work.ts
export function doWork() { ... }
import { Alpine } from "./alpine";
Alpine.global("work", { doWork });

// Another file
import { doWork } from "./work";
const result = doWork();
```

```html
<!-- Template -->
<button @click="work.doWork()">Click</button>
```

## Testing

### After Each Phase
```bash
# Build
npm run build:ts

# Run
go run .

# Test
# - Homepage loads
# - Login works
# - Dashboard loads
# - No console errors
# - No 404s for .js files
```

## Rollback

If any phase has issues:
```bash
# Revert changes
git checkout web/src/  # For TypeScript issues
git checkout templates/PROBLEM.templ  # For template issues

# Rebuild
npm run build:ts
templ generate
go run .
```

## Next Steps

1. **Read** the full plan: `ESBUILD_MIGRATION_PLAN.md`
2. **Start** Phase 0: Add ES exports (1-2 hours)
3. **Test** thoroughly after each phase
4. **Track** progress using checklist in plan
5. **Ask** questions if anything is unclear

## Resources

- **Full Plan**: ESBUILD_MIGRATION_PLAN.md (this document)
- **Old Plan**: ESBUILD_SETUP_OLD.md (archived, incomplete)
- **Alpine Docs**: https://alpinejs.dev/
- **ESBuild Docs**: https://esbuild.github.io/
- **Templ Docs**: https://github.com/a-h/templ

## Support

If you encounter issues:
1. Check the "Troubleshooting" section in the full plan
2. Review the "Testing Checklist" for your phase
3. Use the "Rollback Procedures" if needed
4. Reference the "Quick Reference" patterns

---

**Remember**: This is an incremental migration with clear phases. Take it one phase at a time, test thoroughly, and you'll have a clean, modern codebase ready for launch.