FAQ

FAQ

Why is a demo store "asleep" or 500ing sometimes?

The three reference demos run on real free-tier database backends (Supabase Postgres for print-shop/northline, Convex for broadleaf). Free-tier Postgres projects auto-pause after a period of inactivity, and a paused backend makes the demo's catalog reads fail. This is a real, disclosed tradeoff (see the Decisions Log → free-tier-resilience-and-keepalive), not a hidden bug: the app detects this specific failure shape and renders an honest "this demo may be asleep" state with a retry button instead of a raw error page, and a daily automated job attempts to wake/revive affected backends. If a demo is still down after a retry, the underlying free account may need manual recreation — check the repo's GitHub Actions tab for the keep-alive job's latest run.

Is this production-ready?

Read the README's own current status line rather than assuming either "yes" or the project's older framing: as of 2026-09-22 the full commerce loop (catalog, marketing catalog, search, PDP, CMS, cart, checkout, Stripe payments, orders, accounts, inventory, plugins) is built and shipped, four persistence adapters are real (SQLite, Postgres, MongoDB, Convex), and three genuinely distinct demo stores run live in production. Several third-party integrations are real and unit-tested but currently credential-gated rather than live-verified end to end — see the integrations catalog for the exact status of each one. Treat the README's own status line as the current source of truth; it's updated as things change.

How do I pick a persistence backend?

See the integrations catalog's persistence-adapter table — it lists every adapter (adapter-sqlite, adapter-postgres, adapter-mongodb, adapter-convex, adapter-shopify), which ones are actually live in production today vs. built-but-unverified, and the exact environment variable(s) each one reads. adapter-sqlite is the zero-infra local-dev default; nothing is required to run the app locally.

How do I migrate off Shopify?

Use @mercatus-liber/migrate-shopify (packages/migrate-shopify) — a one-time migration tool, distinct from @mercatus-liber/adapter-shopify (which is a live wrapper that keeps you running on Shopify's API forever). migrate-shopify reads your existing Shopify catalog once (fully cursor-paginated: products, variants, collections, inventory) and writes it into Mercatus Liber's own native persistence through the same public service-layer methods the rest of the app uses — so your target backend's own validation always runs. It defaults to a dryRun: true report (zero writes) so you can see exactly what would be created/skipped before committing. See the package's own README for the full CLI usage and its honest disclosure of what hasn't been live-verified against a real Shopify store yet.