Under the hood of MDN's new frontend

A visible refresh, an invisible overhaul

MDN shipped a new frontend last year that, on the surface, mostly cleaned up styles and unified the site’s look. But the real work took place under the hood: the team reconstructed how MDN pages are assembled, moving from a heavy React wrapper to an architecture that stitches Markdown -> JSON -> server-rendered pages more directly. The payoff? Less client-side glue, smaller bundles, and fewer surprises for contributors who edit docs and translators who maintain localized content.

Why the rewrite was necessary

The previous frontend, yari, began life as a Create React App and slowly became a tangle of ejected configs, hacky Webpack scripts, mixed Sass and modern CSS idioms, and wildly entangled styles. Changes in one place would break another. Even worse: the React boundary never actually understood the site’s static HTML, so the team relied on dangerouslySetInnerHTML and ad-hoc DOM hacks for small interactive pieces like copy buttons. It was, by their own admission, painful to maintain — technical debt piled up and developer velocity slowed to a crawl.

What changed and what it means

MDN’s engineers adopted web components and server components, focused on shipping only what pages actually need, and rebuilt the development baseline and tooling. The result: scoped styling, fewer render-blocking resources, and interactivity that can be attached where it belongs without reparsing the whole page in the browser. It’s faster for readers, easier for contributors, and more sustainable for maintainers. Want to peek under the hood or help out? The project is open-source and the team has publicly documented the details for anyone curious. Will other docs sites ditch heavy SPA shells for leaner, component-driven builds? Time will tell — but MDN just made a strong case.

Sources: developer.mozilla.org, Lobsters