State & ArchitectureBaseline · Widely

URL as a State Store

Mental Model

Storing filters, sort order, and active tabs in React useState evaporates on page reload and breaks link sharing. Encoding view state in URLSearchParams makes the browser's address bar your single source of truth, provided you separate pushState (Back-worthy steps) from replaceState (live edits).

Interactive Simulator

History Hygiene: pushState Spam vs replaceState + Validation

Compare polluting browser history on every keystroke against schema-validated replaceState updates.

Lines of Code
Before
4
After
4
Reflows / Browser Cost
Before
5 history entries for 1 word
After
1 clean history entry
BeforeNaive pushState on Every Input
input.addEventListener('input', (e) => {
  // Typing 'shoes' pushes 5 separate Back-button entries!
  history.pushState(null, '', `?q=${e.target.value}`);
});
Lines: 4Reflows: 5 history entries for 1 wordDependencies: Unescaped raw string interpolation

Pressing Back steps through 'shoe', 'sho', 'sh', 's' instead of leaving the page.

After (Native)URLSearchParams + replaceState
const url = new URL(location.href);
url.searchParams.set('q', query.trim());
history.replaceState(null, '', url);
// Discrete pagination still uses pushState()
Lines: 4Reflows: 1 clean history entryDependencies: Native URL + URLSearchParams

URL stays shareable and bookmarkable while the Back button works as expected.

Under the Hood

The browser's session history stack is an ordered list of (URL, state) tuples that survives reloads and integrates with bfcache. Treating the URL as a state store means avoiding Stale Closures by deriving UI directly from the parsed location rather than mirroring it into duplicate component state.

  1. Parse new URLSearchParams(window.location.search) through a strict validator that coerces types and falls back to safe defaults on malformed query strings.
  2. Call history.pushState() for discrete, Back-navigable transitions (switching tabs, advancing page 1 -> page 2).
  3. Call history.replaceState() for continuous or noisy edits (search-as-you-type, map pan coordinates) so the user's Back button still exits cleanly.
JS
function updateSearchParam(key, value, { replace = false } = {}) {
  const url = new URL(window.location.href);
  value ? url.searchParams.set(key, value) : url.searchParams.delete(key);
  const method = replace ? 'replaceState' : 'pushState';
  window.history[method](null, '', url);
}

Problem Genealogy

  • 2008 (Hashbangs #!): Stuffed SPA routes after # because mutating paths forced full-page reloads.
  • 2011 (HTML5 History API pushState): Allowed clean path/query updates without reloads, though developers routinely mirrored URL state into Redux and watched the two drift out of sync.
  • 2022+ (Navigation API & Typed Routers): Added centralized navigate interception and schema-validated search parameters.

Production Pitfalls

Production Pitfall
  • Dual-source-of-truth desync: Copying ?sort=price into useState('price') on mount and forgetting to listen to popstate leaves the UI stale when the user clicks Back.
  • Calling pushState on every keystroke: Pushing 12 history entries for a 12-letter search query traps users inside your search bar.
When Not to Use
  • When not to use the URL as a state store: Never put sensitive tokens, PII, ephemeral hover/drag coordinates, or multi-kilobyte payloads in the URL (browsers and proxies cap URL lengths around 2–8 KB).

Connections & Logical Next Steps

Seen in Architecture Autopsies

Mechanical Comparisons