Add Search To Your Astro Static Site
Astro is great for static site generation, but it doesn’t come with any built-in search tools out of the box. While some may use third-party tools such as Algolia, I wanted to avoid relying on third-party services.
Enter Pagefind, a static search library for indexing your content and presenting search results on your static site. Pagefind is framework agnostic, but setup can be a little tricky.
Pagefind needs to run after your site has been built, because it analyzes the HTML files to generate the search index. Add a
postbuild script to your
package.json to run Pagefind after your site has been built. The site directory will be the output of Astro’s build (
Adding a Dev Endpoint
A big issue I came across when first solving this, is that there’s no way to inject the pagefind bundle into your site at development time, because the site only exists as memory. I solved this by adding a dev endpoint to my site, which will serve a “fake” Pagefile script filled with 0 results. This way, the script will always be available, and the search results will always be empty. It’s a little hacky, but it works. Create a new file at
src/pages/pagefind/pagefind.js.ts with the following contents:
There’s probably a better way to do this, but this will prevent your site from screaming at you when you try to access the pagefind script at development time. During build time, since Pagefind is run after the site is built, the actual Pagefind script will replace the dev endpoint.
Adding a Searchbar
To keep things simple, I’m going to simply use an
<input> element as a searchbar, just to show how to integrate Pagefind’s library. You can choose to put this anywhere on your site. If you’re using the default Astro template, you can add it to
src/pages/index.astro for example.
What we’re doing here, is listening to the
input event on the searchbar, and then loading the Pagefind script if it hasn’t been loaded yet. Once the script is loaded, we can use the
search function to search the index. The
search function returns the results. Each result has a
data function, which returns the data for that result. In this case, we’re using the
meta.title properties to create a link to the result, and the
excerpt property to show a preview of the result. You can find a reference to the structure returned by
The benefit of asyncronously loading the Pagefind script is that it won’t affect the performance of your site. The script is only loaded when the user starts typing in the searchbar. Allowing you to keep all 100s in your Lighthouse score 😎
Excluding Elements From The Index
Pagefind will index all of the text in the
body element by default, excluding elements like
form. If you want to exclude additional elements from the index, you can add the
data-pagefind-ignore attribute to the element. I recommend doing this on any lists or archive pages to prevent the index from being bloated with duplicate content.
Now you can expose a good search experience to your users, without a third-party provider. It took me a few hours to get this working, so hopefully this will save you some debugging time. You won’t be able to search your site in development, but you can always build your site to test it out.
If you want to see this in action, you can check out the source code for this post.
Thanks for reading! If you have any questions, feel free to reach out to me on Twitter or Discord.