Fern Docs sites are now static, and much faster

In part 1, we rebuilt how docs are stored so a one-page edit only touches one page. That made each page faster to render. Part 2 renders every page ahead of time, when you publish, instead of when a reader asks for it.

Readers get finished pages straight from the edge. Search, Ask Fern, and login work exactly as before.

Better Lighthouse scores on real sites

Here are mobile Lighthouse scores for the same pages on real customer sites, before and after. Lighthouse's mobile test is deliberately strict. It simulates an older Android phone (a 2022 Moto G Power) with a slowed-down CPU on a slow 4G connection.

Every site improved.

We also ran the same test on the introduction page of 17 live Fern Docs sites and 20 docs sites built with a competing docs product. Scores depend a lot on the third-party scripts each company adds, like analytics, consent banners, and chat widgets, so we also compared sites that load similar amounts of them. Fern Docs sites score higher on average in every group. 11 of the 17 Fern Docs sites score 90 or above, and none of the competing sites do. Among sites with few third-party scripts, 11 of the 12 Fern Docs sites score 90 or above, and that group averages 97.

Why the old pages were slower

Every page was sent twice

The old pages sent each page as HTML, then sent it again as a data payload that the browser used to rebuild the page in JavaScript. On the sites above, that second copy was 72% to 75% of the HTML. New pages send the HTML once, so they're 2 to 4 times smaller.

The browser spent seconds running JavaScript

Rebuilding the page in the browser took a lot of JavaScript. On that same simulated phone, the old pages spent 5.0 to 10.7 seconds running scripts before readers could reliably scroll and click. New pages ship JavaScript only for the interactive parts of the page, like search, and spend 0.5 to 1.5 seconds.

Files came from a shared domain

One app served every customer's docs, so it couldn't serve its files from each customer's own domain, especially for sites on a subpath like yourcompany.com/docs. Instead, every page loaded its scripts, stylesheets, and images from a shared Fern domain. That's one more domain the browser has to look up and connect to before it can draw the page.

Faster local preview

fern docs dev now runs the same renderer on your machine that serves your readers, and it's faster and lighter than before:

Try it on your own docs:

fern docs dev

Edits show up in the browser in under a second, and what you preview locally is what your readers see after you publish.

Sites never go slow after a publish

Before, publishing was the moment a site got slow. The old pages were rendered on demand and cached by a hosting platform we didn't fully control, so the only reliable way to show new content was to clear the cache for the whole site. The first reader to visit each page afterward waited for it to be rendered again.

On real customer sites, a page fetched right after a publish used to take a median of 2.7 seconds to start responding, and up to 10.7 seconds. Now the same pages respond in a median of 0.45 seconds, and 9 in 10 respond in under 0.6 seconds.

There's no warm-up period anymore. Each publish produces a complete new version of your site, and readers keep getting the previous version until the new one is fully ready.

More secure by default

A strict Content Security Policy

A Content Security Policy tells the browser which scripts a page is allowed to run. Because the old pages depended on dozens of inline scripts, their policy had to allow inline scripts, eval, and scripts from any HTTPS domain. A policy that broad does little to stop a script injected into the page.

New pages are built ahead of time, so each one ships with a policy that lists a fingerprint of every script it was built with. The browser blocks script tags that weren't part of your published page.

Everything loads from your domain

Before, every docs page pulled its scripts, stylesheets, and images from app.buildwithfern.com, often 80 or more requests per page load.

Now every one of those assets is served from your own domain, and none load from app.buildwithfern.com. If your security team maintains a Content Security Policy or a network allowlist, your docs only need your domain. Readers on corporate networks that block unfamiliar domains get the whole page.

Get the full benefit with one DNS change

If your docs live on a subpath (like yourcompany.com/docs), you don't need to do anything.

If your docs live on a subdomain (like docs.yourcompany.com), your site is already static. A small DNS change makes it faster still, by sending readers straight to the new infrastructure.

Mercoa has already made the switch, and its pages now start responding in a median of 0.12 seconds, down from 0.30 seconds.

To make the change, message us in your shared Slack channel or contact us, and we'll send you the new DNS record.