agentleFS
remix-runremix-run/remix-store/.agents/skills/hydrogen-predictive-search/SKILL.md

hydrogen-predictive-search

Skill218 starsChanged 10 days agoMITView on GitHub

Guide for building predictive search with @shopify/hydrogen. Use when adding, modifying, or reviewing autocomplete/search-as-you-type UI, predictive search route handlers, tracking URLs, custom predictive search fragments, or framework predictive search bindings.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 8 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep rendering app-owned. Hydrogen provides data, state, request lifecycle, and URL helpers — not a dropdown template.

    line 23
  2. Distinctive:

    Use the same request-scoped Storefront client as the app's other Hydrogen handlers and loaders.

    line 35
  3. Very specific:

    When building with a UI framework, check this skill's references/ directory for framework-specific instructions.

    line 41
  4. Very specific:

    Use getPredictiveSearchItemUrl() for predictive result links.

    line 45
  5. Very specific:

    If the storefront uses custom Shopify resource paths, use the local hydrogen-routing skill before wiring predictive search result URLs.

    line 58
  6. Very specific:

    Use getSearchResultUrl() only when constructing a custom search-attributed URL that is not backed by a predictive search item.

    line 60
  7. Distinctive:

    Do not publish a new analytics event for predictive suggestions.

    line 62
  8. Distinctive:

    Use additive fragments when the UI needs extra result fields:

    line 66
  9. Very specific:

    Use the route-handler form for browser-backed autocomplete.

    line 99
  10. Distinctive:

    Use the packaged route handler as the default browser transport.

    line 103
  11. Distinctive:

    Keep UI rendering and layout app-owned.

    line 105
  12. Very specific:

    Use q for the search term so predictive and full search URLs align.

    line 107
  13. Very specific:

    Use the local hydrogen-routing skill for result URLs when the app uses custom Shopify resource paths.

    line 108
  14. Distinctive:

    Keep debounce in the client store.

    line 110
  15. Distinctive:

    Prefer additive fragments over full query overrides.

    line 111

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Hydrogen Predictive Search

Hydrogen predictive search has four layers:

  1. Storefront API query helper in @shopify/hydrogen.
  2. Same-origin route handler at /api/predictive-search.
  3. Framework-neutral client store.
  4. Framework provider/hooks or composables.

Keep rendering app-owned. Hydrogen provides data, state, request lifecycle, and URL helpers — not a dropdown template.

Server Route

Register the packaged route handler in the app's central handleShopifyRoutes() wiring before framework routing. Use the hydrogen-request-handlers skill for the full framework-specific request context, session manager, and Storefront client setup.

import { createPredictiveSearchServerHandlers } from "@shopify/hydrogen";

const predictiveSearchHandlers = createPredictiveSearchServerHandlers();

Use the same request-scoped Storefront client as the app's other Hydrogen handlers and loaders. Do not create a second client inside predictive search code.

The default browser predictive search endpoint is GET /api/predictive-search. Override it with predictiveSearchEndpoint when the JSON route lives elsewhere. The route accepts q plus optional Storefront API controls such as limit, limitScope, types, searchableFields, and unavailableProducts.

Framework UI

When building with a UI framework, check this skill's references/ directory for framework-specific instructions. Framework bindings share the same route, store, and URL contracts.

Tracking URLs

Use getPredictiveSearchItemUrl() for predictive result links. It infers Hydrogen's standard storefront route from the item's __typename and keeps Storefront API trackingParameters without double-encoding:

import { getPredictiveSearchItemUrl } from "@shopify/hydrogen";

const productHref = getPredictiveSearchItemUrl(product, { routes: routeTemplates, term });
const querySuggestionHref = getPredictiveSearchItemUrl(querySuggestion, {
  routes: routeTemplates,
});

Pass {term} for resource items such as products, collections, pages, and articles. These items do not contain the shopper's typed search text, but the destination URL needs it for attribution. Do not pass {term} for SearchQuerySuggestion items; the helper uses querySuggestion.text automatically. Pass {routes: routeTemplates} so query suggestions honor a custom search route. Pass {searchPath} only when the suggestion link intentionally differs from the shared search route; it takes precedence when provided.

If the storefront uses custom Shopify resource paths, use the local hydrogen-routing skill before wiring predictive search result URLs. Do not create predictive-search-only URL callbacks.

Use getSearchResultUrl() only when constructing a custom search-attributed URL that is not backed by a predictive search item.

Do not publish a new analytics event for predictive suggestions. Full search pages can keep their existing search-view analytics; predictive result links carry attribution through tracking parameters.

Custom Fragments

Use additive fragments when the UI needs extra result fields:

import {
  createPredictiveSearchServerHandlers,
  gql,
  makePredictiveSearchQueries,
  queryPredictiveSearch,
} from "@shopify/hydrogen";

const predictiveSearchFragments = {
  product: gql(`
    fragment PredictiveSearchProductFragment on Product {
      vendor
    }
  `),
};

const predictiveSearchHandlers = createPredictiveSearchServerHandlers({
  fragments: predictiveSearchFragments,
});

const queries = makePredictiveSearchQueries({
  fragments: predictiveSearchFragments,
});

const data = await queryPredictiveSearch({
  storefrontClient,
  term,
  query: queries.predictiveSearch,
});

Use the route-handler form for browser-backed autocomplete. Use makePredictiveSearchQueries() when querying directly from server code. Keep fragment names as documented by the API types. Hydrogen composes these with required base fields such as IDs, handles, titles, prices, images, and tracking parameters.

Rules

  • Use the packaged route handler as the default browser transport.
  • Degrade to a normal search without JavaScript. The search entry point must be a real /search link or a role="search" GET form, and the predictive modal's form must submit GET /search natively (formProps() defaults to this). Predictive autocomplete is an enhancement layered on top — never the only way to reach search results. With JS off, the trigger navigates to /search (or submits the term to it) and the full search page renders results server-side.
  • Keep UI rendering and layout app-owned.
  • Preserve trackingParameters on every predictive result link.
  • Use q for the search term so predictive and full search URLs align.
  • Use the local hydrogen-routing skill for result URLs when the app uses custom Shopify resource paths.
  • Render store errors near the search UI.
  • Keep debounce in the client store; do not add ad-hoc debounce in components unless there is a separate UX reason.
  • Prefer additive fragments over full query overrides.
  • Return empty UI for blank terms rather than querying Storefront API.
  • The modal is a native <dialog> opened with showModal(). For backdrop-dismiss, use closedby="any" where supported. For browsers without closedby support, use a pointerdown-plus-click guard: record whether pointerdown started on the dialog backdrop, then close only when the following click also targets the dialog. Do not close on a plain click.self alone — a drag that starts inside and ends on the backdrop can produce an accidental close.

Verify

Done when:

  • Search works without JavaScript: a real /search link or role="search" GET form reaches server-rendered results, and the predictive modal's form submits GET /search natively.
  • Browser autocomplete goes through the same-origin /api/predictive-search route.
  • Every predictive result link preserves trackingParameters (built with getPredictiveSearchItemUrl()).
  • Blank terms render empty UI without querying the Storefront API.
  • Store errors surface near the search UI.
  • The search term uses q so predictive and full search URLs align.

Anti-patterns

  • Gating search behind JavaScript — a search trigger that only opens a JS autocomplete overlay, with no /search link or native GET form underneath, leaves no-JS shoppers with no way to search. The predictive layer must enhance a working /search path, not replace it.
  • Calling Storefront API directly from browser UI when a same-origin route can proxy the request.
  • Reusing /search?predictive=true as the autocomplete API when /api/predictive-search is available.
  • Dropping or manually concatenating tracking parameters.
  • Hard-coding predictive result links separately from the app's routing primitive.
  • Duplicating predictive search state in framework component state when the Hydrogen store already owns request lifecycle, debounce, aborts, and stale response handling.
  • Shipping a visual autocomplete component as the primary abstraction.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.