Pagefind only works in a production build, not in dev

Pagefind, the static-site search index used by Astro Starlight and others, builds its index by scanning the rendered HTML in dist/. That index does not exist while you are running astro dev — the dev server serves pages dynamically and never produces the static HTML Pagefind crawls.

The symptom is a search box that appears in dev but returns either nothing or “search is only available in a production build.” This is not a bug; the dev server is not the place where the index gets built.

To verify search locally, run a production build and then preview it:

pnpm build && pnpm preview

The preview server serves the built dist/ directory, Pagefind has its index, and search works. I learned this in the k0j1iii-handbook project, which uses Starlight; the same gotcha applies to anyone wiring Pagefind into a vanilla Astro site.