@shopify/cli 3.65.1 → 3.65.3

package/dist/assets/hydrogen/starter/guides/predictiveSearch/predictiveSearch.md

@@ -0,0 +1,391 @@
+# Hydrogen Predictive Search
+
+Our skeleton template ships with predictive search functionality. While [regular search](../search/search.md)
+provides paginated search of `pages`, `articles` and `products` inside the `/search` route,
+predictive provides real-time results in a aside drawer for `pages`, `articles`, `products`, `collections` and
+recommended `queries/suggestions`.
+
+This integration uses the storefront API (SFAPI) [predictiveSearch](https://shopify.dev/docs/api/storefront/latest/queries/vpredictiveSearch) endpoint to retrieve predictive search results based on a search term.
+
+## Components Architecture
+
+![alt text](./predictiveSearch.jpg)
+
+## Components
+
+| File                                                                                             | Description                                                                                                                                            |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`app/components/SearchFormPredictive.tsx`](../../app/components/SearchFormPredictive.tsx)       | A fully customizable form component configured to make form `GET` requests to the `/search` route.                                                    |
+| [`app/components/SearchResultsPredictive.tsx`](../../app/components/SearchResultsPredictive.tsx) | A fully customizable search results wrapper, that provides compound components to render `articles`, `pages`, `products`, `collections` and `queries`. |
+
+## Instructions
+
+### 1. Create the search route
+
+Create a new file at `/routes/search.tsx` (if not already created)
+
+### 3. Add `predictiveSearch` query and fetcher
+
+The predictiveSearch fetcher parses the `q` and `limit` formData properties sent
+by the `<SearchFormPredictive />` component and performs the predictive search
+SFAPI request.
+
+```ts
+/**
+ * Predictive search query and fragments
+ * (adjust as needed)
+ */
+const PREDICTIVE_SEARCH_ARTICLE_FRAGMENT = `#graphql
+  fragment PredictiveArticle on Article {
+    __typename
+    id
+    title
+    handle
+    blog {
+      handle
+    }
+    image {
+      url
+      altText
+      width
+      height
+    }
+    trackingParameters
+  }
+` as const;
+
+const PREDICTIVE_SEARCH_COLLECTION_FRAGMENT = `#graphql
+  fragment PredictiveCollection on Collection {
+    __typename
+    id
+    title
+    handle
+    image {
+      url
+      altText
+      width
+      height
+    }
+    trackingParameters
+  }
+` as const;
+
+const PREDICTIVE_SEARCH_PAGE_FRAGMENT = `#graphql
+  fragment PredictivePage on Page {
+    __typename
+    id
+    title
+    handle
+    trackingParameters
+  }
+` as const;
+
+const PREDICTIVE_SEARCH_PRODUCT_FRAGMENT = `#graphql
+  fragment PredictiveProduct on Product {
+    __typename
+    id
+    title
+    handle
+    trackingParameters
+    variants(first: 1) {
+      nodes {
+        id
+        image {
+          url
+          altText
+          width
+          height
+        }
+        price {
+          amount
+          currencyCode
+        }
+      }
+    }
+  }
+` as const;
+
+const PREDICTIVE_SEARCH_QUERY_FRAGMENT = `#graphql
+  fragment PredictiveQuery on SearchQuerySuggestion {
+    __typename
+    text
+    styledText
+    trackingParameters
+  }
+` as const;
+
+// NOTE: https://shopify.dev/docs/api/storefront/latest/queries/predictiveSearch
+const PREDICTIVE_SEARCH_QUERY = `#graphql
+  query predictiveSearch(
+    $country: CountryCode
+    $language: LanguageCode
+    $limit: Int!
+    $limitScope: PredictiveSearchLimitScope!
+    $term: String!
+    $types: [PredictiveSearchType!]
+  ) @inContext(country: $country, language: $language) {
+    predictiveSearch(
+      limit: $limit,
+      limitScope: $limitScope,
+      query: $term,
+      types: $types,
+    ) {
+      articles {
+        ...PredictiveArticle
+      }
+      collections {
+        ...PredictiveCollection
+      }
+      pages {
+        ...PredictivePage
+      }
+      products {
+        ...PredictiveProduct
+      }
+      queries {
+        ...PredictiveQuery
+      }
+    }
+  }
+  ${PREDICTIVE_SEARCH_ARTICLE_FRAGMENT}
+  ${PREDICTIVE_SEARCH_COLLECTION_FRAGMENT}
+  ${PREDICTIVE_SEARCH_PAGE_FRAGMENT}
+  ${PREDICTIVE_SEARCH_PRODUCT_FRAGMENT}
+  ${PREDICTIVE_SEARCH_QUERY_FRAGMENT}
+` as const;
+
+/**
+ * Predictive search fetcher
+ */
+async function predictiveSeach({
+  request,
+  context,
+}: Pick<ActionFunctionArgs, 'request' | 'context'>) {
+  const {storefront} = context;
+  const formData = await request.formData();
+  const term = String(formData.get('q') || '');
+
+  const limit = Number(formData.get('limit') || 10);
+
+  // Predictively search articles, collections, pages, products, and queries (suggestions)
+  const {predictiveSearch: items, errors} = await storefront.query(
+    PREDICTIVE_SEARCH_QUERY,
+    {
+      variables: {
+        // customize search options as needed
+        limit,
+        limitScope: 'EACH',
+        term,
+      },
+    },
+  );
+
+  if (errors) {
+    throw new Error(
+      `Shopify API errors: ${errors.map(({message}) => message).join(', ')}`,
+    );
+  }
+
+  if (!items) {
+    throw new Error('No predictive search data returned');
+  }
+
+  const total = Object.values(items).reduce((acc, {length}) => acc + length, 0);
+
+  return json({term, result: {items, total}, error: null});
+}
+```
+
+### 3. Add a `loader` export to the route
+
+This action receives and processes `GET` requests from the `<SearchFormPredictive />`
+component. These request include the search parameter `predictive` to identify them over
+regular search requests.
+
+A `q` URL parameter will be used as the search term and appended automatically by
+the form if present in it's children prop.
+
+```ts
+/**
+ * Handles predictive search GET requests
+ * requested by the SearchFormPredictive component
+ */
+export async function loader({request, context}: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const isPredictive = url.searchParams.has('predictive');
+
+  if (!isPredictive) {
+    return json({})
+  }
+
+  const searchPromise = predictiveSearch({request, context})
+
+  searchPromise.catch((error: Error) => {
+    console.error(error);
+    return {term: '', result: null, error: error.message};
+  });
+
+  return json(await searchPromise);
+}
+```
+
+### 4. Render the predictive search form and results
+
+Create a SearchAside or similar component to render the form and results.
+
+```ts
+import { SearchFormPredictive } from '~/components/SearchFormPredictive';
+import { SearchResultsPredictive } from '~/components/SearchResultsPredictive';
+
+function SearchAside() {
+  return (
+    <Aside type="search" heading="SEARCH">
+      <div className="predictive-search">
+        <br />
+        <SearchFormPredictive>
+          {({ fetchResults, goToSearch, inputRef }) => (
+            <>
+              <input
+                name="q"
+                onChange={fetchResults}
+                onFocus={fetchResults}
+                placeholder="Search"
+                ref={inputRef}
+                type="search"
+              />
+              &nbsp;
+              <button onClick={goToSearch}>
+                Search
+              </button>
+            </>
+          )}
+        </SearchFormPredictive>
+
+        <SearchResultsPredictive>
+          {({ items, total, term, state, inputRef, closeSearch }) => {
+            const { articles, collections, pages, products, queries } = items;
+
+            if (state === 'loading' && term.current) {
+              return <div>Loading...</div>;
+            }
+
+            if (!total) {
+              return <SearchResultsPredictive.Empty term={term} />;
+            }
+
+            return (
+              <>
+                <SearchResultsPredictive.Queries
+                   queries={queries}
+                   term={term}
+                   inputRef={inputRef}
+                />
+                <SearchResultsPredictive.Products
+                   products={products}
+                   closeSearch={closeSearch}
+                   term={term}
+                />
+                <SearchResultsPredictive.Collections
+                   collections={collections}
+                   closeSearch={closeSearch}
+                   term={term}
+                />
+                <SearchResultsPredictive.Pages
+                   pages={pages}
+                   closeSearch={closeSearch}
+                   term={term}
+                />
+                <SearchResultsPredictive.Articles
+                   articles={articles}
+                   closeSearch={closeSearch}
+                   term={term}
+                />
+                {term.current && total && (
+                  <Link onClick={closeSearch} to={`/search?q=${term.current}`}>
+                    <p>
+                      View all results for <q>{term.current}</q> →
+                    </p>
+                  </Link>
+                )}
+              </>
+            );
+          }}
+        </SearchResultsPredictive>
+      </div>
+    </Aside>
+  );
+}
+```
+
+## Additional Notes
+
+### How to use a different URL search parameter?
+
+- Modify the `name` attribute in the forms input element. e.g
+
+```ts
+<input name="query" />`.
+```
+
+- Modify the fetchers term variable to parse the new name. e.g
+
+```ts
+const term = String(searchParams.get('query') || '');
+```
+
+### How to customize the way the results look?
+
+Simply go to `/app/components/SearchResultsPredictive.tsx` and look for the compound
+component you would like to modify.
+
+Here we add images to each predictive product result item
+
+```diff
+SearchResultsPredictive.Products = function ({
+  products,
+  closeSearch,
+  term,
+}: SearchResultsPredictiveProductsProps) {
+  if (!products.length) return null;
+
+  return (
+    <div className="predictive-search-result" key="products">
+      <h5>Products</h5>
+      <ul>
+        {products.map((product) => {
+          const productUrl = urlWithTrackingParams({
+            baseUrl: `/products/${product.handle}`,
+            trackingParams: product.trackingParameters,
+            term: term.current,
+          });
++         const image = product?.variants?.nodes?.[0].image;
+          return (
+            <li className="predictive-search-result-item" key={product.id}>
+              <Link to={productUrl} onClick={closeSearch}>
++               {image && (
++                 <Image
++                   alt={image.altText ?? ''}
++                   src={image.url}
++                   width={50}
++                   height={50}
++                 />
++               )}
+                <div>
+                  <p>{product.title}</p>
+                  <small>
+                  {product?.variants?.nodes?.[0].price && (
+                    <Money
+                      data={product.variants.nodes[0].price}
+                    />
+                  )}
+                  </small>
+                </div>
+              </Link>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  )
+};
+```

package/dist/assets/hydrogen/starter/guides/search/search.md

@@ -0,0 +1,333 @@
+# Hydrogen Search
+
+Our skeleton template ships with a `/search` route and a set of components to easily
+implement a traditional search flow.
+
+This integration uses the storefront API (SFAPI) [search](https://shopify.dev/docs/api/storefront/latest/queries/search)
+endpoint to retrieve search results based on a search term.
+
+## Components Architecture
+
+![alt text](./search.jpg)
+
+## Components
+
+| File                                                                   | Description                                                                                                                 |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| [`app/components/SearchForm.tsx`](app/components/SearchForm.tsx)       | A fully customizable form component configured to make (server-side) form `GET` requests to the `/search` route.            |
+| [`app/components/SearchResults.tsx`](app/components/SearchResults.tsx) | A fully customizable search results wrapper, that provides compound components to render `articles`, `pages` and `products` |
+
+## Instructions
+
+### 1. Create the search route
+
+Create a new file at `/routes/search.tsx`
+
+### 3. Add `search` query and fetcher
+
+The search fetcher parses the `q` parameter and performs the search SFAPI request.
+
+```ts
+/**
+ * Regular search query and fragments
+ * (adjust as needed)
+ */
+const SEARCH_PRODUCT_FRAGMENT = `#graphql
+  fragment SearchProduct on Product {
+    __typename
+    handle
+    id
+    publishedAt
+    title
+    trackingParameters
+    vendor
+    variants(first: 1) {
+      nodes {
+        id
+        image {
+          url
+          altText
+          width
+          height
+        }
+        price {
+          amount
+          currencyCode
+        }
+        compareAtPrice {
+          amount
+          currencyCode
+        }
+        selectedOptions {
+          name
+          value
+        }
+        product {
+          handle
+          title
+        }
+      }
+    }
+  }
+` as const;
+
+const SEARCH_PAGE_FRAGMENT = `#graphql
+  fragment SearchPage on Page {
+     __typename
+     handle
+    id
+    title
+    trackingParameters
+  }
+` as const;
+
+const SEARCH_ARTICLE_FRAGMENT = `#graphql
+  fragment SearchArticle on Article {
+    __typename
+    handle
+    id
+    title
+    trackingParameters
+  }
+` as const;
+
+const PAGE_INFO_FRAGMENT = `#graphql
+  fragment PageInfoFragment on PageInfo {
+    hasNextPage
+    hasPreviousPage
+    startCursor
+    endCursor
+  }
+` as const;
+
+// NOTE: https://shopify.dev/docs/api/storefront/latest/queries/search
+export const SEARCH_QUERY = `#graphql
+  query Search(
+    $country: CountryCode
+    $endCursor: String
+    $first: Int
+    $language: LanguageCode
+    $last: Int
+    $term: String!
+    $startCursor: String
+  ) @inContext(country: $country, language: $language) {
+    articles: search(
+      query: $term,
+      types: [ARTICLE],
+      first: $first,
+    ) {
+      nodes {
+        ...on Article {
+          ...SearchArticle
+        }
+      }
+    }
+    pages: search(
+      query: $term,
+      types: [PAGE],
+      first: $first,
+    ) {
+      nodes {
+        ...on Page {
+          ...SearchPage
+        }
+      }
+    }
+    products: search(
+      after: $endCursor,
+      before: $startCursor,
+      first: $first,
+      last: $last,
+      query: $term,
+      sortKey: RELEVANCE,
+      types: [PRODUCT],
+      unavailableProducts: HIDE,
+    ) {
+      nodes {
+        ...on Product {
+          ...SearchProduct
+        }
+      }
+      pageInfo {
+        ...PageInfoFragment
+      }
+    }
+  }
+  ${SEARCH_PRODUCT_FRAGMENT}
+  ${SEARCH_PAGE_FRAGMENT}
+  ${SEARCH_ARTICLE_FRAGMENT}
+  ${PAGE_INFO_FRAGMENT}
+` as const;
+
+/**
+ * Regular search fetcher
+ */
+async function search({
+  request,
+  context,
+}: Pick<LoaderFunctionArgs, 'request' | 'context'>) {
+  const {storefront} = context;
+  const url = new URL(request.url);
+  const searchParams = new URLSearchParams(url.search);
+  const variables = getPaginationVariables(request, {pageBy: 8});
+  const term = String(searchParams.get('q') || '');
+
+  // Search articles, pages, and products for the `q` term
+  const {errors, ...items} = await storefront.query(SEARCH_QUERY, {
+    variables: {...variables, term},
+  });
+
+  if (!items) {
+    throw new Error('No search data returned from Shopify API');
+  }
+
+  if (errors) {
+    throw new Error(errors[0].message);
+  }
+
+  const total = Object.values(items).reduce((acc, {nodes}) => {
+    return acc + nodes.length;
+  }, 0);
+
+  return json({term, result: {total, items}});
+}
+```
+
+### 3. Add a `loader` export to the route
+
+This loader receives and processes `GET` requests from the `<SearchForm />` component.
+
+A `q` URL parameter will be used as the search term and appended automatically by
+the form if present in it's children prop
+
+```ts
+/**
+ * Handles regular search GET requests
+ * requested by the SearchForm component and /search route visits
+ */
+export async function loader({request, context}: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const isRegular = !url.searchParams.has('predictive');
+
+  if (!isRegular) {
+    return json({})
+  }
+
+  const searchPromise = regularSearch({request, context});
+
+  searchPromise.catch((error: Error) => {
+    console.error(error);
+    return {term: '', result: null, error: error.message};
+  });
+
+  return json(await searchPromise);
+}
+```
+
+### 4. Render the search form and results
+
+Finally, create a default export to render both the search form and the search results
+
+```ts
+import {SearchForm} from '~/components/SearchForm';
+import {SearchResults} from '~/components/SearchResults';
+
+/**
+ * Renders the /search route
+ */
+export default function SearchPage() {
+  const {term, result} = useLoaderData<typeof loader>();
+
+  return (
+    <div className="search">
+      <h1>Search</h1>
+      <SearchForm>
+        {({inputRef}) => (
+          <>
+            <input
+              defaultValue={term}
+              name="q"
+              placeholder="Search…"
+              ref={inputRef}
+              type="search"
+            />
+            &nbsp;
+            <button type="submit">Search</button>
+          </>
+        )}
+      </SearchForm>
+      {!term || !result?.total ? (
+        <SearchResults.Empty />
+      ) : (
+        <SearchResults result={result} term={term}>
+          {({articles, pages, products, term}) => (
+            <div>
+              <SearchResults.Products products={products} term={term} />
+              <SearchResults.Pages pages={pages} term={term} />
+              <SearchResults.Articles articles={articles} term={term} />
+            </div>
+          )}
+        </SearchResults>
+      )}
+    </div>
+  );
+}
+```
+
+## Additional Notes
+
+### How to use a different URL search parameter?
+
+- Modify the `name` attribute in the forms input element. e.g
+
+```ts
+<input name="query" />`.
+```
+
+- Modify the search fetcher term variable to parse the new name. e.g
+
+```ts
+const term = String(searchParams.get('query') || '');
+```
+
+### How to customize the way the results look?
+
+Simply go to `/app/components/SearchResults.txx` and look for the compound component you
+want to modify.
+
+For example, let's render articles in a horizontal flex container
+
+```diff
+SearchResults.Pages = function({
+  pages,
+  term,
+}: {
+  pages: SearchItems['pages'];
+  term: string;
+}) {
+  if (!pages?.nodes.length) {
+    return null;
+  }
+  return (
+    <div className="search-result">
+      <h2>Pages</h2>
++     <div className="flex">
+        {pages?.nodes?.map((page) => {
+          const pageUrl = urlWithTrackingParams({
+            baseUrl: `/pages/${page.handle}`,
+            trackingParams: page.trackingParameters,
+            term,
+          });
+          return (
+            <div className="search-results-item" key={page.id}>
+              <Link prefetch="intent" to={pageUrl}>
+                {page.title}
+              </Link>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+};
+```