Skip to main content

Local Stencil development

BigCommerce does not output scripts managed through Script Manager when a theme runs through the local Stencil CLI. Hyper Search therefore needs its storefront application script and store-specific window.HSData configuration added temporarily during local development.

warning

Use these steps only in a local or non-production theme. The configuration contains store-specific search connection details: do not commit it to source control or publish it in documentation.

Before you begin​

  • Enable Hyper Search for the storefront in Settings > Storefront.
  • Confirm that Hyper Search works on the hosted storefront.
  • Run the Stencil theme against the same store and channel.

Add the storefront scripts locally​

  1. In BigCommerce admin, open Storefront > Script Manager.
  2. Find the Hyper Search data script for the storefront and copy its script content. It defines window.HSData, including the store hash, channel, search configuration and public search credentials.
  3. Paste that script near the end of your local theme's templates/layout/base.html, before the closing </body> tag.
  4. Add the Hyper Search application script immediately after the data script:
<script
  src="https://hypersearch.hypaapps.com/hyper-search/js/index.js"
  crossorigin="anonymous"
></script>
  1. Confirm that the theme contains the required .s48_hypersearch search input container and #s48_hypersearch-results results container. See Add Hyper Search to your site.
  2. Start or restart Stencil CLI, then test autocomplete and the full results page.

The local theme should now use the same Hyper Search configuration as the hosted storefront.

Remove the temporary configuration​

Before committing or uploading the theme, remove both temporary scripts. The hosted storefront receives current scripts through BigCommerce Script Manager; leaving local copies in the theme can expose stale configuration or load Hyper Search twice.

If local search does not load, compare the browser console and network requests with the hosted storefront. A missing window.HSData object usually means the data script was not copied in full, while a missing .s48_hypersearch or #s48_hypersearch-results element indicates that the theme integration is incomplete.