@techsio/storefront-data/skills/audit-storefront-before-release/SKILL.md

Medusa-first storefront data layer built on TanStack Query.

---
name: audit-storefront-before-release
description: >
  Load this skill before releasing a storefront that uses
  @techsio/storefront-data. Use it to audit SSR hydration, query-key identity,
  storage degradation, cart cache sync, and selected payment-session checkout
  behavior so the storefront does not ship with a hidden split source of truth.
type: lifecycle
library: "@techsio/storefront-data"
library_version: "0.1.0"
requires:
  - implement-ssr-prefetch-and-query-client-boundaries
  - implement-cart-and-checkout-platform-flows
  - configure-pagination-prefetch-and-cache-policy
sources:
  - "TechsioCZ/new-engine:libs/storefront-data/README.md"
  - "TechsioCZ/new-engine:libs/storefront-data/tests/ssr-hydration.smoke.test.tsx"
  - "TechsioCZ/new-engine:libs/storefront-data/tests/shared.browser-storage.test.ts"
  - "TechsioCZ/new-engine:libs/storefront-data/tests/cart.cache-sync.test.ts"
  - "TechsioCZ/new-engine:libs/storefront-data/tests/medusa.flow.test.tsx"
---

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:

```ts
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:

```ts
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:

```ts
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:

```ts
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:

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

Correct:

```txt
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:

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

Correct:

```txt
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:

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

Correct:

```txt
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