Fast Simon & Shopify Integration

Build Search and Discovery experience with Fast Simon, a Shopify Plus Certified Partner

Getting started guide

Hydrogen App

Hydrogen is a React framework and SDK that you can use to build fast and dynamic Shopify custom storefronts.

Getting started guide

Fast Simon For Shopify Hydrogen

React NPM package to support Fast Simon Search and Discovery tools in Shopify Hydrogen Projects.

What is Fast Simon for Shopify Hydrogen?

Fast Simon Shopify Hydrogen is a React library to be used in Shopify Hydrogen apps.

By installing this library on your Hydrogen-based React Shopify storefront, you will be able to render Fast Simon Search and Discovery tools in your app.

Installation Guide

This document will guide you to:

• Configure your Shopify store ready for Fast Simon Shopify Hydrogen.
• Install and use Fast Simon Shopify Hydrogen components in your Shopify Hydrogen app.

Prerequisites

Before installation, authenticate with Fast Simon private NPM packages:

# NPM_TOKEN must hold a read-only token for the private @fast-simon scope.
# PowerShell: use "$env:NPM_TOKEN" — a bare "$NPM_TOKEN" expands to empty and sets no token.
npm config set "//registry.npmjs.org/:_authToken" "$NPM_TOKEN"

Never commit the token. See NPM_AUTH.md for how to obtain a read-only token for the private @fast-simon scope and export it as NPM_TOKEN.

Requirements

• Shopify store
• Hydrogen app
• Fast Simon app installed on your Shopify store
• Shopify custom app with Storefront access token

Configure Hydrogen app config

Update hydrogen.config.js with your shop's domain and Storefront API token.

Expose Shopify Metafields

Fast Simon Search and Discovery uses Metafields in order to customize the UI based on Fast Simon No-code editor configuration. Metafields need to be exposed so that they can be retrieved by your Hydrogen app.

Unfortunately, Shopify does not have a way of exposing Shop Metafields via their admin UI.

We strongly recommend to contact Fast Simon Support, we will expose the relevant Metafields for you.

How to Use Fast Simon In Your Hydrogen App

Installation

1. In your Hydrogen app directory, run

npm install @fast-simon/shopify-hydrogen

2. Create fastsimon.config.json file in your root directory and fill it with your Fast Simon UUID & store id:

{
    "UUID": "",
    "storeID": 0
}

3. Open vite.config.ts and import the Fast Simon plugin:

import fastSimonPlugin from "@fast-simon/shopify-hydrogen/plugin";

4. Add fastSimon()to the list of plugins:

  /// <reference types="vitest" />
  import {defineConfig} from 'vite';
  import hydrogen from '@shopify/hydrogen/plugin';
  import fastSimonPlugin from "@fast-simon/shopify-hydrogen/plugin";
  
  export default defineConfig({
      plugins: [hydrogen(), fastSimonPlugin()],
      resolve: {
          alias: [{find: /^~\/(.*)/, replacement: '/src/$1'}],
      },
      optimizeDeps: {
          include: ['@headlessui/react', 'clsx', 'react-use', 'typographic-base'],
      },
      test: {
          globals: true,
          testTimeout: 10000,
          hookTimeout: 10000,
      },
      server: {
          port: 5000
      },
  });

5. Open App.server.tsx and import FastSimonProviderServer:

import fastSimonPlugin from "@fast-simon/shopify-hydrogen/plugin";

6. Include the FastSimonProviderServer, passing through the request object, UUID and store id from your fastsimon.config.json file:

  function App({request}) {
      const pathname = new URL(request.normalizedUrl).pathname;
      const localeMatch = /^\/([a-z]{2})(\/|$)/i.exec(pathname);
      const countryCode = localeMatch ? localeMatch[1] : undefined;
      const isHome = pathname === `/${countryCode ? countryCode + '/' : ''}`;
  
      return (
          <Suspense fallback={<HeaderFallback isHome={isHome} />}>
              <ShopifyProvider countryCode={countryCode}>
                  <FastSimonProviderServer storeID={fastConfig.storeID} uuid={fastConfig.UUID} request={request}>
                      <CartProvider countryCode={countryCode}>
                          <Suspense>
                              <DefaultSeo />
                          </Suspense>
                          <Router>
                              <FileRoutes
                                  basePath={countryCode ? `/${countryCode}/` : undefined}
                              />
                              <Route path="*" page={<NotFound />} />
                          </Router>
                      </CartProvider>
                      <PerformanceMetrics />
                      {import.meta.env.DEV && <PerformanceMetricsDebug />}
                      <ShopifyAnalytics />
                  </FastSimonProviderServer>
              </ShopifyProvider>
          </Suspense>
      );
  }

You can also provide your UUID and storeID directly instead of creating the fastsimon.config.json

Usage

Collections:

1. Open src/routes/collections/[handle].server.jsx and import FastSimonAppServer:

import {FastSimonAppServer} from "@fast-simon/shopify-hydrogen";

2. To the collection handler function, add fastSimonProps parameter:

export default function Collection({params, fastSimonProps}) {...}

3. Replace the Shopify Grid component by FastSimonAppServer, pass collectionID and fastSimonProps as shown below.

    <Layout>
        <Suspense>
            <Seo type="collection" data={collection} />
        </Suspense>
        <PageHeader heading={collection.title}>
            {collection?.description && (
                <div className="flex items-baseline justify-between w-full">
                    <div>
                        <Text format width="narrow" as="p" className="inline-block">
                            {collection.description}
                        </Text>
                    </div>
                </div>
            )}
        </PageHeader>
        <Section>
            <FastSimonAppServer collectionID={collection.id} fastSimonProps={fastSimonProps}/>
        </Section>
    </Layout>

Search Page:

1. Open src/routes/search.server.jsx and import FastSimonAppServer:

import {FastSimonAppServer} from "@fast-simon/shopify-hydrogen";

2. To the search handler function, add fastSimonProps parameter:

export default function Search({pageBy = PAGINATION_SIZE, params, fastSimonProps}) {...}

3. Replace the Shopify Grid component by FastSimonAppServer, pass query and fastSimonProps as shown below.

  return (
    <SearchPage searchTerm={decodeURI(searchTerm)}>
        <Section>
            <FastSimonAppServer query={decodeURI(searchTerm)} fastSimonProps={fastSimonProps}/>
        </Section>
    </SearchPage>
);