Search

Every WPTom template has site search: the search button in the header (or the menu on phones), or ⌘ K / Ctrl K anywhere. Results show the page and the section, and a click jumps straight to that heading.

Templates: all of them. Service: none (built in), or Algolia if you want it.

The built-in search (no setup)

• When the site is built, the template writes an index of your pages, one record per section, to /search-index.json. Which content goes in is set in src/lib/search-pages.ts.
• The search dialog’s script and the index download only the first time a visitor opens search, so they cost your pages nothing until then.
• Searching happens in the visitor’s browser. There is no service, no key and no cost, and the index updates itself with every build.

Try it: run npm run dev, press ⌘ K (or Ctrl K), type a word from one of your pages, and click a result. To see what is indexed, add /search-index.json to your local address.

For most sites this is all you need.

Switching to Algolia

With a lot of content (hundreds of long pages), the built-in index gets large. Algolia then searches on its servers instead, with typo tolerance and ranking. The dialog looks the same.

1. Create the Algolia application and index

1. Sign up at algolia.com and create an application.
2. In Search → Index, create an index, e.g. my-site.
3. Open Settings → API Keys and copy three values:
   • Application ID
   • Search API Key (search-only: safe to put in the page)
   • Admin API Key (can change the index: keep it secret)

2. Add the settings to .env

PUBLIC_ALGOLIA_APP_ID=ABCD1234
PUBLIC_ALGOLIA_INDEX=my-site
PUBLIC_ALGOLIA_SEARCH_KEY=your-search-only-key
ALGOLIA_ADMIN_KEY=your-admin-key

• The three PUBLIC_ settings go into the page; the search-only key can only search.
• ALGOLIA_ADMIN_KEY is used only by the sync command on your computer. Never add it to Vercel or anywhere a browser can see it.

Search switches to Algolia only when all three PUBLIC_ settings are set; with any one missing, the built-in index is used.

3. Fill the index: the sync command

The sync uploads the index your build produced. Run, in your project folder:

npm run build
npm run search:sync

You should see Synced 214 records to Algolia index "my-site". (with your own count). The command replaces everything in the index with the new records, so running it again is safe.

It reads the settings from .env and looks for the built index in .vercel/output/static/, dist/client/ or dist/. “No search-index.json found” means you haven’t run npm run build.

4. Try it on your computer

1. Restart npm run dev.
2. Open search and type. Results now come from Algolia: in your browser’s developer tools, Network shows requests to algolia.net.
3. In Algolia, Search → Index → my-site lists the records and lets you try queries.

5. Put it online

1. In Vercel, Settings → Environment Variables: add PUBLIC_ALGOLIA_APP_ID, PUBLIC_ALGOLIA_INDEX and PUBLIC_ALGOLIA_SEARCH_KEY. Not the admin key.
2. Redeploy (these are written into the pages at build time).

Keeping it up to date

The Algolia index changes only when you run the sync. After you publish content changes, run npm run build and npm run search:sync again on your computer, with the same content as the deployed site (pull the latest changes first if you edit on the live site).

Changing the texts

The dialog’s label, placeholder, result counts and “nothing found” text are in the content editor under Interface texts (the search group).

Troubleshooting

What you see	Why, and what to do
A page or section is missing	It isn’t in src/lib/search-pages.ts, or the build is older than your change. With Algolia: run the sync again
Set PUBLIC_ALGOLIA_APP_ID, PUBLIC_ALGOLIA_INDEX and ALGOLIA_ADMIN_KEY first.	One of them is missing from .env
Algolia clear failed: 403 (or batch failed)	The admin key is wrong or is the search-only key
No results with Algolia	The index is empty: run the sync. Or the index name differs between .env and Algolia