INSTRUCTIONS

Switching it on

{} (or true) is enough — every field has a default. types is the order of the groups on the results page, restricted to the verticals the site deploys (a type the site has no app for answers an empty group and is dropped). routes are this site’s item-page routes, [slug] replaced by the URL-encoded slug — change one when a route is named differently (posts: "/journal/[slug]"). labels are the group headings. pages (Wix-page content) exists as a type but stays off: a headless site has no Wix pages. install: true records that the seed step installs the Wix Site Search app (below); the deploy never mutates the site.

The deploy (deploy.mjs <vertical…> --stack <stack> --plan plan.json) copies the files below, adds @wix/search to package.json, and writes src/wix/site-search/config.generated.ts from the plan (site/js/wix/site-search-config.generated.ts on the static stack). Do not hand-edit the generated file — edit the plan and redeploy.

The site must be indexed — the one site mutation

Nothing is searchable until the Wix Site Search app (1484cb44-49cd-5b39-9681-75188ab429de) is installed on the site. Before that, every search answers 200 with zero documents — silently, no error. Install it after the content seed, from the project root:

It mints the CLI token in-process, installs the app once (idempotent — an installed app is reported, not re-installed), and prints { installed: "now" | "already" }. The install back-fills the site’s existing content: products were searchable about 26 s later and services about 14 s later on the probe sites — allow half a minute, then smoke-test before wiring any UI: searchAll("<a word from a seeded title>") from the deployed data layer (or the page /search?q=<word>) must return a non-empty group. Zero documents after a minute means the app is not installed or the content is not visible to the index (hidden products, draft posts) — never that the query is wrong. The helper behind the script is templates/shared/seed/site.mjs installSiteSearch(ctx), for a seed that wants to call it itself. How fast a later edit reaches the index was not measured.

The file map (deployed into src/)

Astro stack additionally gets:

Static stack (--stack static): rest/search.ts lands flat as js/wix/search.js beside search-core.js, search-store.js, suggest-store.js, site-search-types.js and the generated config; the stores import the REST twin under the same names. No components — the page renders from the stores (subscribe, render getState(), call actions), like every other vertical there.

Wiring

1. The header box. In the deployed vertical’s SiteLayout.astro (the one that won, if several are deployed), next to the nav or the cart button: <SearchBox client:only="react" placeholder="Search" />. It is a <form role="search"> with a suggestions listbox; Enter with no active row opens /search?q=…. Pass searchPath if the page lives elsewhere, onNavigate to route client-side.
2. The results page ships (pages/search.astro) and mounts SearchResults. Brand it through the layout and the @theme tokens; the component’s own classes read the same tokens.
3. The routes must exist: a hit links to routes[type] — the storefront’s /products/[slug], bookings’ /services/[slug], blog’s /blog/[...slug], events’ /events/[slug]. A site that names one differently says so in the plan.
4. Smoke-test per the section above before calling the surface done.

Contracts

indexed answers “does this site have an index at all”: true when documents came back; false when the response listed no document type — nothing is indexed, the app is not installed; null when it is unknown — zero documents across listed types is ambiguous (no match, an empty catalog, an index still back-filling) and must not be read as “not installed”. The shipped empty state says “still being set up” only on false.

Hard rules

• Never render the index’s url. On a headless site it is "" (products) or an absolute URL on the Wix fallback host pointing at a page this site does not serve (services). Hrefs come from hrefFor(type, slug, config) in core; a hit without a slug renders unlinked.
• Highlights are HTML fragments. Only titleHtml/excerptHtml go into set:html or dangerouslySetInnerHTML, and only after safeHighlight() in core (everything but <mark> is dropped). Never interpolate a raw _highlights string.
• Limits are the service’s. 100 chars for search, 50 for suggest, 3-char minimum for suggest; the core clamps (the service 400s otherwise). federatedSearch has no paging — page 2 is a single-type searchType with offset.
• Products take two requests — the default format carries title and _highlights, the result-format: store-front format carries the slug (urlPart) and neither carries both. The transports run the pair and join on id; when the second fails the products render unlinked. A suggestion row for a product therefore has no href — submit() turns it into a search for its title.
• The search page is noindex (the X-Robots-Tag header in the frontmatter).
• Fail loudly. A non-2xx from the search service surfaces as the store’s error with a retry; the only swallowed failure is the store-front pass (it degrades to unlinked products).
• CMS collections are not indexed — Wix Search has no document type for them. A CMS site searches its collections with queryItems(collectionId, { filters: [{ field, op: "contains", value }] }) (templates/cms); merging that into these groups is the agent’s call, marked as a separate list.

Not verified live — guarded

Two probe sites (a store with bookings, a spa) answered the observations above; the rest of the surface is from the SDK typings and the schema page, and the code degrades where a guess would otherwise show:

• Blog post and event hrefs. No probe site had posts or events. The mappers assume url has the services’ shape (…/<page>/<slug>) and take the last path segment; an empty url → href: "", an unlinked row — never a Wix URL. Verify on a site with posts/events; if url is empty there, the fallback is one read per hit (GET /blog/v3/posts/{id} for the slug) or dropping the type from types.
• Visitor access. Both search surfaces accepted an anonymous visitor token on the probe sites, while the platformized typings say @applicableIdentity APP and the docs show an admin client. If that door closes, the fallback is an Astro API route with auth.elevate(wixSiteSearch.search) per CUSTOM_OPERATIONS.md; the failure shows as the store’s error.
• Preview API. The federated module (suggest, facets, highlights, result-format) is @documentationMaturity preview; _highlights, documentImage, urlPart are wire names. Each is spelled once in search-core.ts.
• Filter operators. inStock $eq was observed; collections $hasSome and discountedPriceNumeric $gte/$lte follow the schema page. A rejected filter surfaces as error.
• Sorts on posts/events (publishDate, startDate) follow the schema page’s sortable fields.
• Store-front document id. The join reads id (else _id); a store-front document without a matching id leaves that product unlinked.
• Event prices (minPrice + currency) follow the schema page; absent → "".
• Propagation of later edits to the index was not measured (the install back-fill was: ≤ 26 s).

Extensions (same module, not shipped)

siteSearch.related({ documentId, documentType }) — “you may also like” on a product page; trending — empty on a new site (no view data), so the empty-input state must not depend on it; federatedAutocomplete — phrase completion. Add each as a function in search.ts and rest/search.ts over a body spelled in search-core.ts.