Single-file web apps: the architecture

How to structure a non-trivial interactive application (100+ lines of JS, multiple UI states, user interactions) in a single HTML file without it becoming an unmaintainable mess. Single-file apps are ideal for personal tools, demos, prototypes, and utilities because they have zero build step, zero dependencies, work offline, and can be shared by email or dropped into any web server. But without structure, they quickly become spaghetti: DOM reads mixed with business logic, state scattered across DOM attributes and global variables, event handlers that directly manipulate other parts of the UI, and no clear flow of data.

Use this structured pattern that mirrors React/Vue's architecture in vanilla JS:

1. CSS VARIABLES AND RESET at top in <style>:

:root { --bg: #1a1a2e; --text: #e8e6e3; }
* { margin: 0; padding: 0; box-sizing: border-box; }

1. SEMANTIC HTML with data attributes for state:

<div id="app">
<div id="entry-list" data-filter="all"></div>
</div>

1. SINGLE <script> at bottom with clear sections:

// ========== STATE ==========
const state = { entries: [], filter: 'all', selectedId: null };

// ========== DOM REFERENCES ==========
const $ = (sel) => document.querySelector(sel);
const dom = { list: $('#entry-list'), detail: $('#entry-detail') };

// ========== RENDER FUNCTIONS ==========
function renderList() {
const filtered = state.entries.filter(e =>
state.filter === 'all' || e.category === state.filter
);
dom.list.innerHTML = filtered.map(e =>
<div class="card" data-id="${e.id}">
<h3>${escapeHtml(e.title)}</h3>
</div>
).join('');
}
function render() { renderList(); renderDetail(); }

// ========== STATE UPDATES ==========
function updateState(changes) {
Object.assign(state, changes);
render();
saveState();
}

// ========== EVENT HANDLERS ==========
// Event delegation on container
dom.list.addEventListener('click', (e) => {
const card = e.target.closest('[data-id]');
if (card) updateState({ selectedId: Number(card.dataset.id) });
});

// ========== INIT ==========
function init() {
const saved = localStorage.getItem('app-state');
if (saved) Object.assign(state, JSON.parse(saved));
render();
}
init();

KEY PRINCIPLES:

• State is the single source of truth
• render() is idempotent
• Event handlers only call updateState()
• Data flows one way: event -> updateState -> render -> DOM
• Use event delegation on containers, not listeners on individual elements

This is React's unidirectional data flow model (event -> state -> render) implemented in vanilla JavaScript. It scales surprisingly well because: (1) All state is in one place — easy to debug, serialize, and reason about. (2) render() is the only function that touches the DOM — no scattered DOM mutations. (3) Event handlers are thin — they just update state. (4) The architecture naturally prevents the most common bug in vanilla JS apps: state being split between JavaScript variables and DOM attributes that get out of sync.

Building interactive tools in a single HTML file