The shop sells two things: original watercolour paintings (one of each, ever) and open-edition prints. Originals sell out permanently. Prints don't. The question the architecture has to answer is: how does the site know which originals are still available, and how quickly does it reflect a sale?
The naive answer is to fetch from Medusa at build time and bake the sold status into the static HTML. That works until a painting sells between deploys — the site shows it as available, someone clicks "Add to cart," Medusa rejects the request, and the experience is broken. Rebuilding on every sale is an option, but it couples the storefront's uptime to Medusa's webhook reliability.
The naive answer in the other direction is to fetch from Medusa client-side on every page load and render nothing until the data arrives. That's a spinner on a content site. The paintings are the product. Making visitors wait to see them is the wrong trade.
The actual solution has two layers with clearly defined responsibilities.
Layer 1: build-time hint
Every painting in the content collection has an optional sold field in its frontmatter:
---
title: "Autumn Morning"
sold: true
---
When sold: true, the build-time effects are:
- Catalog feed: the original variant is excluded from the Google/Meta product catalog TSV. No point advertising something that can't be bought.
-
JSON-LD: the product structured data uses
OutOfStockfor availability. Google doesn't index it as a purchasable product. -
OG tags:
product:availabilityis set to"oos".
None of these affect the shop UI. A sold-out painting still has a page, still shows in the gallery, still shows the print options. The sold flag is a build-time signal to external systems, not a UI gate.
The flag is kept in sync automatically. bun run sync reads stocked_quantity from Medusa for every product and patches the frontmatter:
↕ autumn-morning → sold: true
↕ winter-estuary → removed sold flag (back in stock)
↕ in the output means a patch was written. Running sync before deploying keeps the catalog and structured data accurate without manual frontmatter edits.
Layer 2: runtime hydration
The shop grid is static Astro HTML. Every card renders with data-status="available" by default — the optimistic assumption. The original price, the "Add to cart" button, the availability badge: all rendered at build time, all assuming the painting is available.
After the page loads, a plain <script> block calls the Medusa store API and patches each card:
async function hydrateAvailability() {
const products = await fetchProducts() // cached promise, fires once per page
cards.forEach((card) => {
const handle = card.dataset.handle
const availability = products.get(handle)
const originalAvailable = availability?.originalAvailable ?? true // optimistic fallback
card.dataset.status = originalAvailable ? 'available' : 'sold'
if (!originalAvailable) {
card.querySelector('.variant-original')?.setAttribute('data-sold', '')
}
})
}
hydrateAvailability()
data-sold on the original variant row triggers CSS: the price gets a strikethrough, the row fades slightly, the "Add to cart" button disappears. The card stays in the grid — sold originals are visible as FOMO and context, not hidden. Prints on the same painting remain fully purchasable.
No framework. No Svelte island. No loading state. The grid is visible and interactive immediately; the sold indicators arrive silently a few hundred milliseconds later without shifting anything.
What happens when Medusa is down
The optimistic fallback on line 6 above is intentional. If fetchProducts() fails — Medusa is restarting, the VPS is briefly unreachable — every card stays data-status="available". Visitors can browse. The cart still works. If someone tries to add a sold original, Medusa rejects the cart request and the UI shows the error then.
The worst case is a few extra "sorry, sold out" cart errors during a brief backend outage. The alternative — blocking the grid on a Medusa response — would mean a broken shop during any downtime. For a low-traffic art shop, optimistic-with-graceful-degradation is the right default.
The filter system
The shop grid has filters: show all / available originals only / prints only / by theme. The filters use data-hidden (not display:none) driven by data-status and data-tags:
function applyFilters() {
cards.forEach((card) => {
const hidden = shouldHide(card, activeFilter, activeTags)
card.dataset.hidden = String(hidden)
})
}
CSS transitions on data-hidden give the appearance/disappearance a fade rather than a jump. The "available originals" filter count updates after hydrateAvailability() completes — it reads the live data-status values, not the build-time assumptions.
Why two layers instead of one
Build-time data is fast and free — it's just frontmatter. Runtime data is live and accurate. The split is about matching the right data source to the right consumer:
- External systems (Google, Meta) see the build-time state. They cache it. A slightly-stale catalog entry means a sold original might briefly appear in Google Shopping — a bad click, but not a broken purchase (Medusa rejects the cart). Running
bun run syncbefore each deploy keeps the gap small. - The shop UI sees the runtime state. A "available" badge on an actually-sold painting is a much worse experience — someone browses, adds to cart, gets rejected. That one must be live.
bun run sync closes the gap before each deploy, so the build-time state is never more than one deploy behind. In practice, originals sell slowly enough that the gap is rarely more than a few hours.
If you're applying this on a different stack, the principle generalises: optimistic static HTML + silent runtime patch + accept that the worst case is a cart error. The trick is being honest about which data source serves which consumer, and not making the visitor wait for the slow one.
When this pattern doesn't fit
Optimistic-with-graceful-degradation is the right default for a low-traffic shop where originals sell on the order of days. It's the wrong default for a flash sale, a sneaker drop, or anything where stock depletes in seconds and a misleading "available" badge would mean hundreds of cart errors a minute. At that point the spinner stops being a UX failure and starts being an honest signal — "we're checking, because the answer changes faster than we can ship HTML."
That's the full series. The stack behind nadiapoe.co.uk: Astro 6 + Svelte on Cloudflare Pages, Medusa v2 on a €3.29/mo Hetzner VPS, and a handful of patterns that took longer to figure out than they should have.
