# @fast-simon/shopify-hydrogen

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

Latest version **1.0.10** (published 2026-09-14) · ISC license · 0 weekly downloads

## Install

```sh
npm install @fast-simon/shopify-hydrogen
pnpm add @fast-simon/shopify-hydrogen
yarn add @fast-simon/shopify-hydrogen
bun add @fast-simon/shopify-hydrogen
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.10 |
| Published | 2026-09-14 |
| First published | 2022-11-16 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 104.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | fast-simon |

## Links

- npm: https://www.npmjs.com/package/@fast-simon/shopify-hydrogen
- npm.io page: https://npm.io/package/@fast-simon/shopify-hydrogen

## Dependencies (1)

- [@fast-simon/utilities](https://npm.io/package/@fast-simon/utilities.md) 1.0.7

## Recent versions

- 1.0.10 (latest) — 2026-09-14
- 1.0.11-beta.3 (beta) — 2026-09-14
- 1.0.11-beta.2 — 2026-09-09
- 1.0.11-beta.1 — 2026-09-09
- 1.0.11-beta.0 — 2026-09-09
- 1.0.9 — 2026-09-02
- 1.0.10-beta.5 — 2026-09-01
- 1.0.10-beta.4 — 2026-07-01
- 1.0.10-beta.3 — 2026-07-01
- 1.0.10-beta.2 — 2026-06-30
- 1.0.10-beta.1 — 2026-06-30
- 1.0.10-beta.0 — 2026-06-30
- 1.0.8 — 2026-06-30
- 1.0.9-beta.4 — 2026-06-30
- 1.0.9-beta.3 — 2026-06-30
- … 17 more at https://npm.io/package/@fast-simon/shopify-hydrogen/versions

## README

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

[Getting started guide]('https://instantsearchplus.zendesk.com/hc/en-us/categories/360000839131-Getting-Started-with-Fast-Simon')


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

[Getting started guide]('https://shopify.dev/custom-storefronts/hydrogen')

# 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:

```bash
# 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](../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
```shell
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:
```json
{
    "UUID": "",
    "storeID": 0
}
```
3. Open ```vite.config.ts``` and import the Fast Simon plugin:
```typescript
import fastSimonPlugin from "@fast-simon/shopify-hydrogen/plugin";
```

4. Add ```fastSimon()```to the list of plugins:
```typescript
  /// <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```:
```typescript
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```:
```jsx
  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```:
```typescript
import {FastSimonAppServer} from "@fast-simon/shopify-hydrogen";
```
2. To the collection handler function, add ```fastSimonProps``` parameter:
```jsx
export default function Collection({params, fastSimonProps}) {...}
```

3. Replace the Shopify Grid component by ```FastSimonAppServer```, pass ```collectionID``` and ```fastSimonProps``` as shown below.
```jsx
    <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```:
```typescript
import {FastSimonAppServer} from "@fast-simon/shopify-hydrogen";
```
2. To the search handler function, add ```fastSimonProps``` parameter:
```jsx
export default function Search({pageBy = PAGINATION_SIZE, params, fastSimonProps}) {...}
```

3. Replace the Shopify Grid component by ```FastSimonAppServer```, pass ```query``` and ```fastSimonProps``` as shown below.
```jsx 
  return (
    <SearchPage searchTerm={decodeURI(searchTerm)}>
        <Section>
            <FastSimonAppServer query={decodeURI(searchTerm)} fastSimonProps={fastSimonProps}/>
        </Section>
    </SearchPage>
);
```

---
_Source: https://npm.io/package/@fast-simon/shopify-hydrogen · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._