Htmx/docs/Issues

Issues and API Improvement Tracker

This folder tracks known design/API smells in the current template stack, with proposed fixes and their trade-offs.

Use this section for:

• Capturing developer pain points before they are forgotten
• Aligning on possible API improvements
• Comparing implementation cost vs DX benefit
• Planning staged, low-risk migrations

Files

• Component-API-Smells.md - exhaustive problem catalog and solution options
• Improvement-Options-and-Costs.md - decision matrix with cost/consequence analysis
• Roadmap.md - phased adoption plan
• Component-by-Component-Concerns.md - component-level complaint inventory and improvements
• Components/00-API-Limitations-and-Workarounds.md - component API limitations and practical workarounds
• Components/00-API-Design-Guidelines.md - component API design principles for future changes

Scope

This is intentionally broader than bug tracking. Many entries are not defects; they are DX and API design weaknesses (inconsistency, discoverability, ergonomics, safety defaults, and maintainability concerns).

Ground Rules

1. Keep issues concrete and reproducible.
2. Include at least one realistic solution.
3. Always state consequences (breaking change risk, complexity, perf, AOT constraints).
4. Prefer incremental migration paths over large rewrites.