Note: This documentation was created after investigating why certain product options weren't persisting in the URL or triggering prefetch behavior. The root cause was that these features are automatically enabled only for "Variant Options" and not for "Modifier Options" in BigCommerce. If your product options aren't persisting or prefetching, check if they are configured as variant options in your BigCommerce admin panel. Here a small doc about it, hope it can helps other.

Product Options Persistence

This document explains how product options persistence works in our e-commerce application, including URL parameters and prefetching mechanisms.

Overview

Product options can be configured to persist their values in the URL and enable prefetching behavior. This is automatically handled based on whether an option is marked as a "variant option" in BigCommerce.

How It Works

1. Variant Options and Persistence

The persist property for a product option is determined by BigCommerce's isVariantOption flag:

// In data-transformers/product-options-transformer.ts
return {
  persist: option.isVariantOption,
  type: 'swatch-radio-group',
  // ... other properties
};

When persist is true for an option:

• Its value is maintained in the URL parameters
• Prefetching is enabled when hovering over option values

2. URL Parameter Management

The ProductDetailForm component manages URL parameters for persistent options.

This allows users to:

• Share product configurations via URL
• Navigate back to previous configurations
• Maintain selected options during page refreshes

3. Prefetching Mechanism

When persist is true, the form enables prefetching of option combinations.

Benefits of prefetching:

• Faster response times when selecting options
• Smoother user experience
• Reduced loading time for variant changes

Technical Implementation

The feature is implemented across several components:

1. Option Transformation

   • Located in data-transformers/product-options-transformer.ts
   • Transforms BigCommerce API data into application fields
   • Sets the persist property based on isVariantOption

2. Form Component

   • Located in vibes/soul/sections/product-detail/product-detail-form.tsx
   • Manages URL parameters for persistent fields
   • Handles prefetching logic

3. URL State Management

   • Uses nuqs for URL parameter management
   • Maintains selected options in the URL
   • Enables sharing and navigation

Note: This is the default behavior in Catalyst. You could enable persistence to any option by changing data-transformers/product-options-transformer.ts