History restore handling with htmx:historyRestore. Use when: restoring page state on back/forward navigation, re-initializing Alpine.js after history restore, fixing stale content on back button.
localStorage for history restorehtmx:historyRestore fires when a cached page is restoredlucide.createIcons() after restorehtmx.config.historyCacheSize to control cache size (default: 10)<script nonce="{{ request.csp_nonce }}">
document.addEventListener('htmx:historyRestore', function() {
// Re-render Lucide icons (SVG replacement)
if (typeof lucide !== 'undefined') {
lucide.createIcons();
}
});
</script>
<script nonce="{{ request.csp_nonce }}">
document.addEventListener('DOMContentLoaded', function() {
htmx.config.historyCacheSize = 20; // cache last 20 pages
htmx.config.historyEnabled = true; // default
htmx.config.refreshOnHistoryMiss = true; // full reload if cache miss
});
</script>
{# Don't cache this interaction in history #}
<button hx-post="{% url 'forum:toggle_like' topic.pk %}"
hx-target="#like-btn"
hx-push-url="false">
Like
</button>
<script nonce="{{ request.csp_nonce }}">
document.addEventListener('htmx:historyCacheMiss', function(event) {
// Cache expired — do a full page load instead of showing stale content
event.detail.path && (window.location.href = event.detail.path);
});
</script>
// WRONG — huge history cache consuming localStorage
htmx.config.historyCacheSize = 1000; // eats user's localStorage
// WRONG — not re-initializing after restore
// Alpine components broken, Lucide icons missing after back button
| Signal | Problem | Fix |
|---|---|---|
| Icons disappear on back button | Lucide not re-initialized | Call lucide.createIcons() on historyRestore |
| Alpine components broken after back | State not re-initialized | Listen for htmx:historyRestore |
| Stale data on back navigation | Cache shows old content | Set refreshOnHistoryMiss = true |
& .\.venv\Scripts\python.exe -m ruff check . --fix
& .\.venv\Scripts\python.exe -m ruff format .
& .\.venv\Scripts\python.exe manage.py check --settings=app.settings_dev