astro-pagefind: static site search for Astro, built on Pagefind

A search index that is a build artefact, not a service

astro-pagefind is an Astro integration for Pagefind static site search. The framing in the README is that it is an integration for Pagefind, which is the part that matters: Pagefind is the component doing the indexing and the searching, and this package wires it into an Astro build.

What the integration adds is listed under features, and the first two entries describe the whole model. It builds the Pagefind index upon a static build, and it serves a previously prebuilt search index in astro dev mode.

That is a different architecture from a hosted search service. There is no search server, no API key, and no per-query network call to a third party. The index is produced at build time, shipped as static files next to the site, and queried in the browser. The cost of that design is freshness: the search reflects the state of the site at the last build.

The audience is Astro site authors who want a search box without adding an operational dependency. A documentation site, a small product site, a blog with enough pages that scrolling stops working, these are the cases where a build-time index is the right size of solution, and the cases where running a search cluster is not.

The package is MIT licensed, published on npm as astro-pagefind, and the primary language of the repository is Astro, with the integration itself written as a TypeScript package in the packages/ directory.

Three lines of config, one import in the page

The installation is a single npm install:

npm i astro-pagefind

Then the integration goes into the Astro config:

//astro.config.ts

import { defineConfig } from "astro/config";
import pagefind from "astro-pagefind";

export default defineConfig({
  integrations: [pagefind()],
});

And the search component goes into a page:

---
import Search from "astro-pagefind/components/Search.astro";
---

<Search instance="search" className="pagefind-ui" searchboxOptions={{ placeholder: "search" }} />

The three parameters on the component are worth pausing on, because they are where the integration earns its place. The instance attribute names the search instance, which is what makes more than one search box on a page possible. The className is applied to the underlying Pagefind UI so you can style it with your own CSS rather than accepting the defaults. And searchboxOptions passes configuration into the search box itself, where the placeholder is the obvious one.

A working example is kept in the repository, at packages/example, with the layout at packages/example/src/layouts/Main.astro, and the README points at it for a fuller picture than the snippet above.

The integration itself takes no options in the example, which is worth noting, because the configuration surface is not where the complexity of this package lives.

Pagefind 1.5 moved the goalposts, and the README says so

The README has a section headed Pagefind 1.5.0, and it is the most important part of the documentation for anyone starting today.

Pagefind introduced component-based UI in version 1.5.0, and the README states that it is now much easier to integrate the Pagefind UI into Astro projects. New users are encouraged to integrate the Pagefind UI component directly instead of using the astro-pagefind/components/Search.astro component, and that component is now in maintenance mode and will not receive any new UI-related features.

The replacement path needs two pieces. You import the PagefindConfig component to get the Pagefind bundle path wired correctly, and then you place the pagefind-searchbox element:

---
import PagefindConfig from "astro-pagefind/components/PagefindConfig.astro";
---

<PagefindConfig />
<pagefind-searchbox></pagefind-searchbox>

For a project starting now, the difference between the two paths is small in lines of code and large in maintenance. The package's component is stable and will keep working, but the improvements will land in Pagefind's own component, so a site built on the old path will need a deliberate migration rather than an upgrade.

The README also says that for details about the Pagefind UI you should consult the Pagefind documentation directly, which is an admission of where the boundary of this package now lies. The integration is the Astro plumbing, and the user interface belongs to Pagefind.

Custom base paths, several search boxes, and view transitions

Three features in the list exist for sites that are not the simplest case, and each of them corresponds to a real obstacle.

Supports a customized base URL path matters when the site is not served from the domain root. A search index that is fetched from a fixed path breaks the moment the site is deployed under a subdirectory, and this integration lets you set the base the index is served from.

Supporting multiple instances of the component on a page is the second one. The instance attribute in the example is what makes this work, so a documentation site can have a search box in the header and a second one in a sidebar, each with its own results, and each instance needs to be addressable rather than sharing one global state.

The third is support for Astro view transitions. A site using client side navigation between pages has to re-initialise the search UI when the page changes, because the component that wired it up has been replaced. Handling that is the kind of detail that separates an integration that works on a demo from one that works on a site that uses view transitions everywhere.

The last feature on the list is allowing index config to be passed to Pagefind, with an example at packages/example/astro.config.ts. That is the escape hatch for the cases the integration does not model, since Pagefind's own indexing has options that the integration does not need to expose on its own.

Together these make the package usable in a site that has more than one search box, is served from a subpath, and navigates without full page loads. Those are common properties of a real documentation site, which is where this package will mostly be used.

The monorepo behind a two file integration

The repository layout shows a much larger project than the integration itself, which is normal for a package that maintains an example application and several published packages.

The root is a private workspace named root, with pnpm 12.13.0 as the package manager and Node 18 or newer as the engine requirement. The scripts show the shape of the work: dev runs the example package with a filter, build:all runs a recursive build across the packages, check and check:fix run Biome, and release runs the release script in the astro-pagefind package specifically.

The tooling choices are modern and fairly opinionated. Biome 2.5.15 handles both formatting and linting through the format:write and check scripts, with a staged variant for pre-commit use. Commitlint with the conventional config runs alongside husky, which is the prepare script. Renovate is configured for dependency updates, and there is a .nvmrc for the Node version, a .mise.toml for tool versions, and a .zed/ directory, which suggests the maintainer develops in Zed.

The CI workflow is ci.yaml, and the commit history is conventional enough for commitlint to be worth enforcing.

The release history shows the project crossing a major version during 2026. v1.8.6 is dated 2026-03-25, v2.0.0 on 2026-05-10, and v2.0.1 on 2026-07-03, with the last push to the repository on 2026-10-19. The 2.0 line is where the Pagefind 1.5 integration work lives, which matches the README's guidance about the new component path.

Where the limits are, and what a hosted index would change

Two constraints are worth stating before you commit.

The first is freshness, and it comes straight from the architecture. In astro dev mode the integration serves a previously prebuilt search index, so while you are writing a new page, the search will not find it until you rebuild. On a site that publishes frequently that is a non-issue, because the deployed site was built from the same commit as the deployed index. In local development it is a moment of confusion, and it is worth knowing before you file a bug about your new page not being searchable.

The second is the maintenance mode status of the package's own component. The Search.astro component will keep working, and it will not gain features. Any new UI capability lands in Pagefind, and picking it up means switching to the PagefindConfig plus pagefind-searchbox path.

The alternative approach is a hosted search service, and the difference is not the quality of the results, it is the operational model. A hosted service indexes on demand, so content is searchable the moment it is published, and it can rank, filter and suggest across a corpus that changes continuously. In exchange you have a network call per query, a dependency on somebody else's availability, an API key to manage, and a service to pay for.

For a static documentation site, the build-time index wins on simplicity, and the hosted service wins on freshness and on ranking. A project that expects its content to change without a rebuild, or that wants search features beyond what Pagefind provides, is the case where the trade goes the other way.

Editorial conclusion

astro-pagefind suits an Astro site that needs a search box and does not want to run or pay for a search service, and it suits teams that want the search index produced by the same build that produces the pages, so a deployment cannot publish a site whose search is out of date. It does not suit a site with content that changes after the build, because the index is a build artefact, and it does not suit a team that wants the package's own search component to gain features, because that component is in maintenance mode and new work is expected upstream in Pagefind. Check three things before you adopt it: that you are willing to use the Pagefind UI component rather than the package's Search.astro, because the README says the latter will not receive UI features, that you understand the dev mode serves a stale index until you rebuild, and that your build pipeline can run the Pagefind indexing step, which is the part the integration adds. The last push to the repository was on 2026-10-19 and the newest release is v2.0.1 from 2026-07-03.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. shishkin/astro-pagefind on GitHub