The web was built on HTML — documents connected by links, rendered by browsers, readable by anyone. Then we broke it. We wrapped content in JavaScript bundles, hid it behind authentication walls, and made it invisible to machines. It's time to fix that.
What Happened
Somewhere around 2013, the industry decided HTML wasn't enough. React happened. Single-page applications happened. Suddenly every website was a JavaScript application that happened to render in a browser. The URL bar became decorative. The back button became a game of Russian roulette.
The result: the average web page now ships ~500KB of compressed JavaScript. It makes 30+ API calls to load a single view. It breaks if you have a screen reader. It breaks if you have a slow connection. It breaks if you're a search engine. It breaks if you're an AI agent trying to read it.
The irony: We built the most successful hypermedia system in history — the World Wide Web — then spent a decade replacing it with something worse.
The Five Principles
HTML over JSON
Send rendered HTML to the browser, not raw data that needs client-side code to become a UI. HTML is the browser's native language. JSON is a data interchange format. Use each for what it's designed for.
Server Authority
The server owns the truth. The client is a rendering surface, not a state machine. When the server sends HTML, it's sending the complete, authoritative representation of the UI. No sync bugs. No stale caches.
Progressive Enhancement
Start with HTML that works. Layer in interactivity with HTMX, Alpine, or vanilla JS. If JavaScript fails — and it does, constantly — the page still works. Forms still submit. Links still navigate. Content is still readable.
Real URLs
Every piece of content should have a URL. Not a route in a client-side router — a real URL that returns real HTML when you curl it. URLs are the addressing system of the web. Use them.
The Browser Is a Hypermedia Client
Stop fighting the browser. It's not a "JavaScript runtime" — it's a hypermedia client. It fetches documents, renders them, and follows links. That's not a limitation. It's the most powerful, widely deployed application platform ever built.
The AI Angle
Here's what nobody predicted: AI agents can read HTML, follow links, and submit forms. They cannot execute your React components.
When you build a hypermedia-driven site, you're not just making it accessible to humans with slow connections. You're making it accessible to every AI agent, every search engine, every crawler, every tool that speaks HTTP. You're building for the next generation of the web without even trying.
The future of the web isn't JSON APIs consumed by JavaScript SPAs. It's HTML documents — rendered server-side, connected by real links, enriched with hypermedia controls — consumed by humans and AI agents alike. Here's why →
What This Looks Like in Practice
| SPA approach | Hypermedia approach |
|---|---|
| Fetch JSON → parse → diff → patch DOM | Request HTML → swap into page |
| Client-side routing library | Real URLs with real responses |
| Redux / Zustand state management | Server is the source of truth |
| Webpack / Vite / 300 node_modules | HTML from the server + HTMX (14kb) |
| ~180KB JS minimum for a "hello world" | ~14KB for full interactivity |
Further Reading
- Why HTML Wins — the technical case for hypermedia
- Edge-First Architecture — where hypermedia meets Cloudflare
- The Surfable Web — knowledge graphs as websites