MDN Web Docs launched a new frontend last year, serving over 25 million monthly visitors who rely on it for web development docs. The visible change? A simplified, unified design across pages. The real upgrade hides in the code: they scrapped a bloated React app called Yari, riddled with technical debt, for a leaner stack built on Web Components and Lit. This matters because MDN’s site must load fast globally, handle complex features like browser compatibility tables and localization in 40+ languages, and stay maintainable for a small team plus thousands of contributors.
The old architecture started strong but decayed. Writers craft docs in Markdown across Git repos. A build tool converts them to HTML, bundles into JSON with metadata, then the frontend—running server-side rendering (SSR)—assembles full pages with nav, tables, and l10n. Output lands in cloud buckets for CDN delivery. Simple on paper, messy in practice.
Yari’s Downfall: Classic React Pitfalls
Yari began as a Create React App (CRA), a quickstart that bit them hard. CRA’s defaults clashed with MDN’s static-heavy needs, forcing an “eject”—exposing a sprawling Webpack config and hacky scripts. Maintenance turned painful: every fix or feature piled on debt.
CSS fared worse. Heavy Sass use mixed with CSS variables created a stylistic mess. No scoping meant changes rippled unpredictably—one tweak broke distant components. Absent build tools for code-splitting, they shipped a massive, render-blocking CSS file loaded by every user, even for unused features. Bundle sizes ballooned; page loads suffered.
The killer flaw? React as a thin wrapper over pre-built static HTML. To make React “aware” of this content, they hacked in awareness via custom props and hydration tricks. This hybrid defeated React’s strengths—no true SPA benefits, just overhead. Result: slower renders, harder debugging, stalled innovation. React debt is common; MDN’s scale (millions of UVs, intricate tables pulling live data) amplified it.
The New Stack: Lighter, Smarter, Faster
They rebuilt from static-first principles. Core shift: ditch React for vanilla Web Components powered by Lit, a 5KB library for reactive components without framework lock-in. Build tool? Vite, which cranks out sub-100ms dev server startups and tiny production bundles via ES modules and Rollup.
CSS overhaul used Tailwind and PostCSS for utility-first styles—scoped by default, no globals, auto-purged to ~10KB critical CSS. No more blobs; now tree-shaken and lazy-loaded. SSR stays, but simplified: server renders HTML shells, client sprinkles interactive bits only where needed. Hydration? Minimal, targeting compat tables and search.
Numbers tell the story. Old Yari: 200KB+ JS/CSS per page, 2-3s loads on slow networks. New: under 50KB JS, 20KB CSS, sub-1s TTFP. Lighthouse scores jumped to 95+ on mobile. Team velocity? Fixes that took days now take hours; new features like improved search landed faster.
Skeptical take: Web Components aren’t perfect—browser support gaps force polyfills, and Lit adds a learning curve. But for docs sites, it’s ideal: standards-based, future-proof, no vendor risk. MDN proves heavy frameworks often overkill for content sites.
Why this matters beyond MDN: Exposes React’s maintenance trap, especially post-CRA era. With tools like Vite and Lit maturing, teams can build complex UIs leaner. For devs, MDN loads quicker, updates smoother—critical when debugging at 2 AM. Broader web wins: Mozilla invests in open standards, not lock-in. If MDN can pivot, so can you.
