Skip to main content

Gesso Commerce

API library for connecting Gesso frontends with various commerce backends.​

Introduction​

Setup​

Testing​

Uses Vitest. Spec files are colocated with source files (*.spec.ts, *.spec.tsx).

Notes​

Compatibility Notes (Phased Cart Architecture)​

Recent internal improvements introduced phased cart state (initPhase, activeCartPhase, collectionPhase) and an explicit migration from a temporary placeholder cart (id '') to the first real server cart. These changes are backwards compatible:

  • Public hook contract (useCart) is unchanged (method names & return shape preserved).
  • Plugin interfaces (Shopify, BigCommerce, Drupal Commerce, etc.) are not modified; only initialization timing is tightened.
  • Placeholder migration runs only when a real cart id first appears; if a plugin already returns a real id immediately, behavior is identical.
  • Phases never regress (e.g. once initPhase === 'ready' it does not return to fetching).

Potential edge issues now mitigated:

  • Eliminates lingering phantom placeholder entries in multi-cart scenarios.
  • Ensures cookie (gesso-cartId) is written promptly, reducing duplicate anonymous cart creation risk.
  • Guarantees lastStableCart records the real cart (not the placeholder) for accurate rollback & empty-state logic.

If writing a new plugin:

  1. Always return a stable id for any persisted cart.
  2. Return undefined (or a terminal cart) only when no active cart exists yet; the provider will supply a placeholder until one is created.
  3. Avoid relying on the placeholder cart persisting after a real cart id is available; that sentinel is internal only.

If you observe unexpected behavior, enable development logging and inspect the phased state to confirm transitions (initPhase, activeCartPhase). Open an issue with a reproduction including those values.