This skill builds on the SSR, cart/checkout, and cache-policy skills. Use it when the app is already wired and you want a release-time audit.

Audit storefront before release

Run through each section before shipping.

SSR and hydration checks

Check: server prefetch reuses the client cache after hydration

Expected:

tsx

import { getServerQueryClient } from "@techsio/storefront-data/server/get-query-client"
import { storefront } from "@/src/lib/storefront"

const queryClient = getServerQueryClient()
await queryClient.prefetchQuery(
  storefront.hooks.products.getListQueryOptions({
    region_id: "reg_123",
    country_code: "cz",
    limit: 24,
  })
)

Fail condition: the hydrated client immediately refetches the same data because the server and client query inputs differ. Fix: reuse the exact hook-owned query options and pass the same region-sensitive inputs on both sides.

Check: no client bundle imports server/get-query-client

Expected:

tsx

"use client"

import { StorefrontDataProvider } from "@techsio/storefront-data/client/provider"

Fail condition: a client component imports @techsio/storefront-data/server/get-query-client. Fix: keep server query-client work in Server Components and the provider in client code.

Cache and storage checks

Check: the storefront is not writing active-cart state with app-local query keys

Expected:

import { syncCartCaches } from "@techsio/storefront-data/shared/cart-cache-sync"
import { storefront } from "@/src/lib/storefront"

syncCartCaches(queryClient, storefront.queryKeys.cart, cart)

Fail condition: app code calls setQueryData or invalidateQueries with hand-written cart keys. Fix: reuse the shared cart-cache sync helpers and preset query keys.

Check: cart persistence still behaves when storage is unavailable

Expected:

import { createLocalStorageValueStore } from "@techsio/storefront-data/shared/storage-value-store"

const cartStorage = createLocalStorageValueStore({
  key: "shop-cart-id",
})

Fail condition: the app assumes localStorage is always available or crashes when storage access fails. Fix: keep the shared storage seam and test the screen with storage disabled or unavailable.

Checkout checks

Check: selected payment-session behavior is exercised

Expected:

const completeCheckout = storefront.flows.checkout.useCompleteCheckout({
  cartId,
  regionId,
})

Fail condition: only the happy path is tested where the first payment session already matches the desired provider. Fix: exercise selected-session reuse, missing-session cases, and stage-specific checkout errors.

Check: the flow layer owns checkout completion

Expected:

const completeCheckout = storefront.flows.checkout.useCompleteCheckout({
  cartId,
  regionId,
})

await completeCheckout.mutateAsync()

Fail condition: the app completes checkout through direct SDK calls or custom mutations. Fix: route checkout completion back through the shared flow wrappers.

Common Mistakes

CRITICAL Browser-only happy-path verification

Wrong:

plaintext

Only test the screen after `pnpm dev` with client-side navigation.

Correct:

plaintext

Test an SSR-prefetched route and confirm the hydrated client reuses the prefetched cache.

A storefront can look correct in client-only testing while still breaking in App Router SSR or hydration.

Source: libs/storefront-data/tests/ssr-hydration.smoke.test.tsx

HIGH Skipping selected-payment-session edge cases

Wrong:

plaintext

Only test one checkout path where the first payment session already matches the final provider.

Correct:

plaintext

Test selected-session reuse, missing-session cases, and staged checkout errors.

The hard checkout failures live in selected-session and stage-specific behavior, not only in the happy path.

Source: libs/storefront-data/tests/medusa.flow.test.tsx

HIGH Ignoring storage degradation and cross-tab behavior

Wrong:

plaintext

Assume localStorage always exists and one tab is enough to validate cart persistence.

Correct:

plaintext

Check cart persistence when storage is unavailable and when another tab mutates the same key.

Shared browser storage is part of the platform contract. Release review has to include degraded storage and cross-tab synchronization paths.

Source: libs/storefront-data/src/shared/storage-value-store.ts, libs/storefront-data/tests/shared.browser-storage.test.ts

Pre-Deploy Summary

Server-prefetched routes hydrate without key drift
No client code imports server/get-query-client
Cart cache sync uses shared helpers and preset query keys
Storage degradation and cross-tab cart behavior were checked
Checkout completion goes through the shared flow layer
Selected payment-session and staged error cases were exercised

@techsio/storefront-data