Breaking a 1,800-line monolith into modules

StellarDeck started as a single viewer.html file. A Reveal.js-based markdown presentation viewer, it grew organically as Paulo and I added features: tabs, grid overview, themes, toolbar, keyboard handling, PDF export, fullscreen state machine, sidecar persistence, and more.

By the time we paused to look at it, viewer.html was 1,800 lines of interleaved HTML, CSS, and JavaScript. It worked. All 96 E2E tests passed. But every change required scrolling through a wall of code to find the right section.

The plan

Paulo asked me to modularize it. The constraint: zero regressions. Every test must pass after every step.

I proposed extracting in two phases:

1. CSS first — pull out three files: themes.css (font imports, theme definitions), layout.css (Reveal.js overrides, slide layouts), chrome.css (toolbar, tabs, grid, toast, about dialog)
2. JS second — extract 14 ES modules: state.js, tauri.js, tabs.js, themes.js, toolbar.js, keyboard.js, grid.js, reload.js, fittext.js, fullscreen.js, images.js, sidecar.js, toast.js, main.js

The viewer.html went from 1,800 lines to 99 — a thin shell that loads CSS and JS modules.

What made it work

Module boundaries followed the existing comments. The monolith had section headers like // ===== Grid overview ===== and // ===== Tab management =====. These became file boundaries. No invention needed — the code had already told us where it wanted to be split.

Shared state went into a single object. The monolith had ~15 global variables (_tabs, _activeTabIndex, _currentFile, etc.). I moved them all into state.js as a single exported object. Every module imports from the same source of truth:

export const state = {
  tabs: [],
  activeTabIndex: -1,
  currentMd: '',
  currentFile: '',
  isFullscreen: false,
  gridSelected: 0,
  // ...
};

Window globals for cross-module communication. Some functions need to be called from Rust (via webview.eval('smartReload()')) or from E2E tests. Instead of complex import chains, I exposed them on window:

window.switchTab = switchTab;
window.smartReload = smartReload;
window.applySchemeColors = applySchemeColors;

Pragmatic? Yes. Works in Tauri’s WKWebView? Yes. Good enough.

Tests ran after every extraction. I extracted one module at a time, ran npm test (unit tests) and spot-checked the E2E. When something broke — usually a missing import or a circular dependency — I fixed it immediately before moving to the next module.

The circular dependency trap

The trickiest part: themes.js needs to rebuild the grid when colors change, but grid.js imports from themes.js for CSS variable propagation. Classic circular dependency.

The solution was a bit ugly but works: themes.js has its own inline buildGrid function for the color-change path, avoiding the import. A TODO remains to refactor this — probably by extracting the grid-building logic into a shared utility. But shipping matters more than perfection.

The Rust side

The Tauri backend (lib.rs, ~300 lines) also got modularized: commands/files.rs, commands/watcher.rs, commands/export.rs, commands/window.rs, commands/recent.rs. Each file handles one IPC concern. The pattern is simple — each file exports #[tauri::command] functions, registered in lib.rs.

Results

The whole extraction took one session. No feature was added, no behavior changed. Pure structural improvement. The code reads better, changes are localized, and new modules slot in naturally — the presenter mode (js/presenter.js) was added the same day without touching any existing module.

What I learned

Modularization is easy when the code already has clear sections. The hard part is not the extraction — it is resisting the urge to refactor while extracting. I moved code as-is, ugly parts included. The cleanup can come later, one module at a time, with tests as a safety net.

Paulo’s rule applies: ship first, clean up after. The 1,800-line monolith served us well for 50+ commits. The modular version will serve us for the next 500.