I added search to all three of my AI-curated directory sites last month. The choice wasn't obvious — there are at least four options with real adoption — so here's the breakdown I actually ran through before landing on Pagefind.
The four options I considered
Pagefind is a Rust-based static search library. It runs at build time, generates an index in /_pagefind/, and serves everything as static files. No backend, no API key, no per-query billing. It ships a prebuilt UI (PagefindUI) that you can mount on any element, and it supports WebAssembly for in-browser querying.
Algolia DocSearch is free for open-source documentation sites, $49/month for commercial sites below a certain crawl limit. It indexes your content via their crawler (or an API push), stores it on Algolia's infrastructure, and gives you a hosted search widget. Fast, polished, and battle-tested — it's what most major docs sites use.
Lunr.js is a client-side search library. You build the index at build time, serialize it to JSON, and ship it with the page. The browser loads the entire index on first search. Works offline, no external dependency, but the index size grows linearly with content, and there's no incremental loading.
FlexSearch is a newer alternative to Lunr with better performance characteristics and smaller bundle size, but the same core trade-off: you ship the whole index to the browser upfront.
Why Pagefind won
The decisive factor was index size management. My directories have 500-1,000 entries per site, each with a multi-paragraph generated description. A Lunr index for 1,000 entries would be 2-4MB shipped with every page load. Pagefind shards its index and loads chunks lazily as the user types — so the initial load is under 30KB (the WASM binary + a small manifest), and individual chunk fetches happen on demand.
The second factor was cost. Algolia DocSearch's commercial tier runs $49/month per site. I'm running three sites on a total infrastructure budget of roughly $25/month. Pagefind is free.
The third factor was the deploy model. Because everything in /_pagefind/ is a static file, Cloudflare Pages caches it at the edge with no configuration. There's no API to rate-limit, no service availability to depend on, no API key to rotate.
The SearchDialog implementation
The search component is a <dialog> element with a Pagefind UI mounted inside it. I load the pagefind-ui.js script lazily — only when the dialog is first opened — to keep it off the critical path:
function loadPagefind() {
if (loaded || !root) return;
loaded = true;
var s = document.createElement("script");
s.src = "/_pagefind/pagefind-ui.js";
s.onload = function () {
if (window.PagefindUI) {
new window.PagefindUI({ element: root, showSubResults: true, resetStyles: false });
}
};
s.onerror = function () {
root.innerHTML = '<p>Search index not available yet (first build). Try again after next deploy.</p>';
};
document.head.appendChild(s);
}
The s.onerror handler is the part most tutorials skip. On the first deploy of a new Cloudflare Pages site, the /_pagefind/ directory doesn't exist yet — Pagefind only runs during the build. If a user opens search before the first full build completes, pagefind-ui.js 404s. Without the error handler, you get a silent failure. With it, you get a legible message.
The <dialog> element is the right primitive here: it handles focus trapping automatically, Escape closes it natively, and backdrop: CSS pseudo-element gives you the dimmed overlay without JavaScript. The Cmd+K keyboard shortcut is wired with document.addEventListener("keydown", ...) — no library needed.
What Pagefind doesn't do
Two gaps I've hit:
No query logging. Pagefind runs entirely in the browser and doesn't send queries anywhere. For a commercial directory, knowing what users search for is valuable — it tells you which models or games to add, and which compare pages to prioritize. With Algolia you get this for free. With Pagefind you'd need to add a thin logging layer (a fetch POST to an analytics endpoint on each query event). I haven't built this yet.
No fuzzy matching out of the box. Pagefind does stemming and basic substring matching, but "stabilty diffusion" (typo) won't match "stable diffusion". Algolia's typo-tolerance is significantly better. For an AI tools directory where model names are long and often misremembered, this matters. I'll probably add a query-suggestion layer that does fuzzy pre-matching before handing off to Pagefind.
Quick comparison table
| Pagefind | Algolia DocSearch | Lunr.js | |
|---|---|---|---|
| Cost | Free | $49/mo (commercial) | Free |
| Index location | Static files | Algolia cloud | Shipped with page |
| Initial JS load | ~30KB | ~80KB | ~10KB + index |
| Index size scalability | Chunked, lazy | Server-side | Linear, upfront |
| Typo tolerance | Basic stemming | Strong | Weak |
| Query logging | No | Yes | No |
| Build-time integration | Yes | Crawler / push API | Yes |
For a static site on a tight infrastructure budget with 500-1,000 entries, Pagefind is the right default. If the site were larger or if I needed typo tolerance and query analytics without building them myself, Algolia would be worth the cost.
Part of an ongoing 6-month experiment running three AI-curated directory sites. The technical claims here are real; this article was AI-assisted.
Top comments (0)