Switch search from Pagefind to Algolia by teallarson · Pull Request #835 · ArcadeAI/docs

teallarson · 2026-02-27T21:35:48Z

Summary

Replaces Pagefind's build-time static search index with Algolia's crawler-based search (no build step needed — Algolia crawls the live site automatically)
Adds a custom AlgoliaSearch component using react-instantsearch with a keyboard-accessible modal (⌘K), theme-aware light/dark styling, and brand red hit highlights
Removes pagefind, rehype-stringify, remark, remark-rehype deps and the custompagefind build script
Fixes a pre-existing bug where /site.webmanifest 404'd because the middleware matcher didn't exclude .webmanifest files

Test plan

Search button appears in navbar with correct light/dark theming
⌘K opens the search modal
Typing returns results with brand red highlights on matched text
Clicking a result navigates to the correct page
Escape / clicking backdrop closes the modal
pnpm build completes without a Pagefind step

🤖 Generated with Claude Code

Note

Medium Risk
Replaces the site-wide search implementation and related build tooling, which can impact navigation/UX and production discoverability if Algolia env/indexing is misconfigured. Changes are mostly isolated to UI wiring and build scripts, with a small middleware matcher tweak.

Overview
Switches docs search from a build-time Pagefind index to an Algolia react-instantsearch modal search (⌘/Ctrl+K) wired into the Nextra Layout via search={<AlgoliaSearch />} and disables Nextra’s built-in search.

Removes the Pagefind indexing pipeline (deleted scripts/pagefind.ts, dropped custompagefind from build/postbuild, and removes pagefind/remark/rehype-related deps), adds Algolia env var templates in .env.local.example, and updates styling/DOM targeting in globals.css for the new search button + highlighted hits.

Fixes a middleware routing issue by excluding *.webmanifest from the matcher so /site.webmanifest can be served without interception.

^{Written by Cursor Bugbot for commit 25b7afe. This will update automatically on new commits. Configure here.}

Replaces Pagefind's build-time static search index with Algolia's crawler-based search. The index is populated automatically by Algolia's crawler — no build step needed. Adds a custom InstantSearch modal component that is theme-aware (light/dark) and uses the brand red for hit highlights. Also fixes a pre-existing bug where site.webmanifest 404'd in dev because the middleware matcher didn't exclude .webmanifest files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel · 2026-02-27T21:35:53Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Mar 1, 2026 6:21pm

`React.ComponentType<{ components?: ... }>` was incompatible with `MDXContent` returned by @mdx-js/mdx's evaluate(), due to React 19 components returning ReactNode (including undefined) while @types/mdx expects Element | null. Using React.ElementType resolves the boundary without type suppressions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

teallarson · 2026-02-27T22:09:20Z

app/_components/toolkit-docs/components/documentation-chunk-renderer.tsx

not related but docs weren't building right on my branch until i made this change.

- Only initialize algoliasearch when all three env vars are present; show a setup instructions message in the modal otherwise - Add safeHref() to reject non-relative/non-https hit URLs (XSS defense) - Remove unused inputRef, FOCUS_DELAY_MS, and the focus useEffect — SearchBox autoFocus already handles this correctly Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

@uidotdev/usehooks is already a dependency. useEventListener handles add/remove lifecycle internally, removing the boilerplate. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replaces hardcoded hsl(347 ...) values with var(--primary) from @arcadeai/design-system tokens and color-mix() for transparent tints. Dark mode text override removed since --primary resolves identically in both modes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace hardcoded neutral/dark: pairs with semantic tokens where the mapping is clean and visually equivalent: - text-neutral-900 dark:text-white → text-foreground - text-neutral-400/500 dark:text-neutral-500/400 → text-muted-foreground - border-neutral-200/300 dark:border-white/10 → border-border - bg-white dark:bg-neutral-900 (modal panel) → bg-popover Hover states on hits and the trigger button bg retain explicit neutral/white values since bg-muted dark resolves too dark for those. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…idotdev/usehooks@2.4.1 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

teallarson · 2026-02-27T22:25:12Z

app/_components/algolia-search.tsx

+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault();
+        setIsOpen((prev) => !prev);
+      }
+      if (e.key === "Escape") {
+        setIsOpen(false);
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, []);


it would be neat to either upgrade @uidotdev/usehooks to a verstion that has useEventListener or use https://tanstack.com/hotkeys/latest (never tried it but tanstack is usually legit)

but for now, a useEffect is the best i've got

teallarson · 2026-02-27T22:26:45Z

package.json

    "react": "19.2.3",
    "react-dom": "19.2.3",
    "react-hook-form": "7.65.0",
+    "react-instantsearch": "^7.26.0",


algolia's react library https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

cursor · 2026-02-27T22:27:42Z

app/_components/algolia-search.tsx

+                    hitComponent={({ hit }) => (
+                      <SearchHit hit={hit as unknown as HitRecord} />
+                    )}
+                  />


Hits component always renders alongside empty query message

Medium Severity

The Hits component renders unconditionally, but Algolia returns results for empty queries by default. When the search modal opens, users see the "Start typing to search the docs…" message from EmptyQuery and a list of search results from Hits at the same time. The Hits component needs to be conditionally hidden when no query has been entered.

Additional Locations (1)

app/_components/algolia-search.tsx#L61-L71

I think this is fine? I like the way this shows top docs pages and also prompts for input when empty. Open to other opinions.

teallarson · 2026-02-27T22:30:35Z

middleware.ts

 export const config = {
  matcher: [
-    "/((?!api|_next/static|_next/image|favicon.ico|manifest|_pagefind|public|.*.svg|.*.png|.*.jpg|.*.jpeg|.*.gif|.*.webp|.*.ico|.*.css|.*.js|.*.woff|.*.woff2|.*.ttf|.*.eot|.*.otf|.*.pdf|.*.txt|.*.xml|.*.json|.*.py|.*.mp4).*)",
+    "/((?!api|_next/static|_next/image|favicon.ico|manifest|public|.*.svg|.*.png|.*.jpg|.*.jpeg|.*.gif|.*.webp|.*.ico|.*.webmanifest|.*.css|.*.js|.*.woff|.*.woff2|.*.ttf|.*.eot|.*.otf|.*.pdf|.*.txt|.*.xml|.*.json|.*.py|.*.mp4).*)",


I had a bunch of 404s locally from this. Idk if I should have just ignored them. This fixed it.

evantahler

goodbye pagefind!

Spartee · 2026-03-01T10:49:15Z

nice

Adds Configure with attributesToSnippet, imports Snippet component, and updates SearchHit to show a content snippet when present (new per-section index format) with fallback to description highlight for existing flat records. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel bot had a problem deploying to Preview February 27, 2026 21:38 Failure

vercel bot deployed to Preview February 27, 2026 21:50 View deployment

teallarson commented Feb 27, 2026

View reviewed changes

vercel bot deployed to Preview February 27, 2026 22:13 View deployment

teallarson and others added 2 commits February 27, 2026 17:13

Remove "Search by Algolia" footer from search modal

1d913ca

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace useEffect keyboard handler with useEventListener

31d25ad

@uidotdev/usehooks is already a dependency. useEventListener handles add/remove lifecycle internally, removing the boilerplate. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel bot had a problem deploying to Preview February 27, 2026 22:17 Failure

teallarson marked this pull request as ready for review February 27, 2026 22:20

teallarson requested review from evantahler, sdserranog and torresmateo February 27, 2026 22:20

vercel bot had a problem deploying to Preview February 27, 2026 22:20 Failure

teallarson and others added 2 commits February 27, 2026 17:21

Revert to useEffect for keyboard handler — useEventListener not in @u…

79545f9

…idotdev/usehooks@2.4.1 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel bot deployed to Preview February 27, 2026 22:24 View deployment

teallarson commented Feb 27, 2026

View reviewed changes

cursor bot reviewed Feb 27, 2026

View reviewed changes

teallarson commented Feb 27, 2026

View reviewed changes

evantahler approved these changes Feb 27, 2026

View reviewed changes

vercel bot deployed to Preview March 1, 2026 18:21 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Switch search from Pagefind to Algolia#835

Switch search from Pagefind to Algolia#835
teallarson wants to merge 9 commits intomainfrom
teallarson/algolia-search

teallarson commented Feb 27, 2026 •

edited by cursor bot

Loading

Uh oh!

vercel bot commented Feb 27, 2026 •

edited

Loading

Uh oh!

teallarson Feb 27, 2026

Uh oh!

teallarson Feb 27, 2026

Uh oh!

teallarson Feb 27, 2026

Uh oh!

cursor bot left a comment

Uh oh!

cursor bot Feb 27, 2026

Uh oh!

teallarson Feb 27, 2026 •

edited

Loading

Uh oh!

teallarson Feb 27, 2026

Uh oh!

evantahler left a comment

Uh oh!

Spartee commented Mar 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

teallarson commented Feb 27, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

vercel bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

teallarson Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

teallarson Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

teallarson Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 27, 2026

Choose a reason for hiding this comment

Hits component always renders alongside empty query message

Uh oh!

teallarson Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

teallarson Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

evantahler left a comment

Choose a reason for hiding this comment

Uh oh!

Spartee commented Mar 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

teallarson commented Feb 27, 2026 •

edited by cursor bot

Loading

vercel bot commented Feb 27, 2026 •

edited

Loading

teallarson Feb 27, 2026 •

edited

Loading