Skip to main content

Getting Started

Welcome to the Fast Simon integration guide! Follow these steps to set up and use Fast Simon in your Catalyst app.

Requirements​

Before you begin, ensure you have the following:

  • BigCommerce Store: A live or development BigCommerce store with the Fast Simon app installed and product data synced.
  • Catalyst App: A Catalyst storefront built on Next.js, ready for customization.
  • Fast Simon App: Installed and configured on your BigCommerce store.

Enable Fast Simon Features:​

  1. Log in to your Fast Simon Dashboard and navigate to Upsell & Cross-sell > Advanced Configuration.

  2. Confirm that the following functionalities are activated:

  • Collections
  • Search Results Page
  • Autocomplete
  • Upsell & Cross-sell

Installation​

Set up the required Fast Simon SDK packages in your Catalyst project.

Install Fast Simon Packages:​

Go to the core directory and run the following commands:

# Using pnpm
pnpm install @fast-simon/storefront-sdk @fast-simon/types

# Using npm
npm install @fast-simon/storefront-sdk @fast-simon/types

# Or using yarn
yarn add @fast-simon/storefront-sdk @fast-simon/types

This installs:

  • @fast-simon/storefront-sdk – the core library for fetching Fast Simon data (search results, collections, recommendations, etc.).
  • @fast-simon/types – TypeScript definitions for Fast Simon data structures and event names, which will help with type safety and IntelliSense.

Configure Environment Variables​

Next, set up your Catalyst project with your Fast Simon credentials. In your project’s root, create (or edit) a .env.local file and add your Fast Simon Store ID and Site UUID:

NEXT_PUBLIC_FAST_SIMON_STORE_ID=<your_fast_simon_store_id>
NEXT_PUBLIC_FAST_SIMON_UUID=<your_fast_simon_site_uuid>
FAST_SIMON_COOKIE_SECRET=<your_generated_cookie_secret>

Replace <your_fast_simon_store_id>, <your_fast_simon_site_uuid>, and <your_generated_cookie_secret> with your actual credentials. You can generate a cookie secret using openssl rand -hex 32.

Fast Simon Integration in Catalyst​

Using the Fast Simon SDK in Your Catalyst App​

The example below demonstrates how to integrate the Fast Simon SDK into your Catalyst project by creating a utility that initializes the Fast Simon client and session. This utility can then be used to query Fast Simon data from any component or page.

  1. Navigate to core/lib and create a new file named get-fast-simon.ts.
  2. Copy and paste the following code into the file:
import {
  CookieSessionStorage,
  createFastSimonClient,
  FastSimonSession,
} from '@fast-simon/storefront-sdk';
import { cookies } from 'next/headers';
import { cache } from 'react';

export const getFastSimon = cache(async () => {
  const fastSimonSession = await getFsSessionForRequest();

  return createFastSimonClient({
    fastSimonSession,
    searchPersonalization: true,
    collectionPersonalization: true,
  });
});

export async function getFsSessionForRequest() {
  const cookieStore = await cookies();

  const storage = new CookieSessionStorage({
    cookieName: 'fastSimonSession',
    cookieSecret: process.env.FAST_SIMON_COOKIE_SECRET || 'fallback-secret',
    maxAge: 60 * 60 * 24 * 5, // 5 days
  });

  return await FastSimonSession.init(cookieStore.toString(), storage);
}
  1. Use the getFastSimon utility in your Next.js data fetching methods to query the Fast Simon API.

Remember to replace the placeholder values in your .env.local file with your actual Fast Simon credentials from the dashboard.

By following these steps, you'll have Fast Simon integrated into your Catalyst storefront, unlocking powerful search, discovery, and personalization capabilities tailored for BigCommerce.