Astro Medusa Storefront is an open-source ecommerce starter that pairs Astro's static-first islands architecture with Medusa v2 as a headless commerce backend to produce a storefront that deploys to Cloudflare Workers.
What is Astro Medusa Storefront?
Astro Medusa Storefront is a starter template for building high-performance ecommerce sites with Astro 6, React 19, and Medusa v2. It takes a Medusa backend URL, publishable key, Stripe keys, and a default region as environment configuration and outputs a static-first storefront with product catalog, product detail pages, cart, multi-step checkout, and order confirmation. The template uses Tailwind CSS v4 for styling, Nanostores for client-side cart state, and React Hook Form with Zod for checkout validation. It is authored by Michal Bystryk and distributed under the MIT license.
Key Features
- Static-first islands architecture — Product pages, store listing, and landing page are statically generated at build time; cart, checkout, and navigation hydrate as interactive React islands, so non-interactive pages ship zero JavaScript.
- Edge deployment on Cloudflare Workers — The Astro adapter targets Cloudflare Workers, and the README provides
yarn buildandyarn previewcommands for a production build and local preview. - Medusa v2 integration — A Medusa SDK singleton in
src/lib/sdk.tsconnects to your backend; webhooks trigger re-deploys whenever products are created, updated, or deleted. - Real-time inventory checks — Product variant stock data is fetched client-side on page load, preventing stale availability on otherwise static pages.
- Region-aware routing — Every route is prefixed with an ISO-2 country code (e.g.,
/:country/store), and middleware handles region detection and country-based routing, with pricing, currency, and shipping resolved via Medusa regions. - Stripe-powered checkout — A multi-step checkout flow covers address, shipping, and payment, configured with
PUBLIC_STRIPE_KEY. - Tailwind CSS v4 styling — No Tailwind config file; theme customization lives in CSS with
@theme, powered by the Vite plugin. - Nanostores cart state — Cart state persists client-side via Nanostores and
localStorage.
Who is it for?
- Developers building on Medusa v2 — start from a working storefront with clean module separation instead of wiring Medusa's SDK and checkout flow from scratch.
- Agencies and freelancers — deliver a fast, edge-deployed storefront for clients who already run a Medusa backend, and customize the modular structure in
src/modules. - Performance-focused ecommerce teams — use the islands architecture and static generation to minimize JavaScript and keep pages lightweight.
What can you do with Astro Medusa Storefront?
- Store owners: deploy a headless storefront on Cloudflare Workers that uses your existing Medusa v2 backend for catalog, pricing, and shipping.
- Developers: extend or replace modules for cart, checkout, products, and order confirmation, and add new routes under
src/pages/[countryCode]. - Teams testing Medusa: spin up a local development environment with
yarn devagainst a local Medusa server and Stripe test keys.
How does it work?
Clone the repository, install dependencies with Yarn 4.x, copy .env.example to .env, and fill in your Medusa backend URL, publishable key, default region, Stripe key, and optional S3 and InPost settings. Run yarn dev for local development on port 8000, then yarn build to generate a Cloudflare Workers production build. Medusa webhooks keep statically generated product pages in sync by triggering a re-deploy on catalog changes.
FAQ
Is Astro Medusa Storefront free?
Yes, it is open-source under the MIT license, so you can use, modify, and deploy it without licensing fees.
What prerequisites do I need?
You need Node.js 18 or newer, Yarn 4.x, a running Medusa v2 backend, and a Stripe account. The README also notes that your Medusa backend must have CORS configured to allow requests from your storefront origin.
How does inventory stay accurate if pages are static?
Product variant availability is fetched client-side on page load from the Medusa backend, so shoppers see current stock even though the page itself is statically generated.
Does the storefront support multiple countries?
Yes. Routes are prefixed with ISO-2 country codes, and middleware performs region detection and country-based routing. Pricing, currency, and shipping options are resolved through Medusa regions.
Can I customize the design?
Yes. Styling uses Tailwind CSS v4 with a zero-config Vite plugin; you customize the theme in CSS using @theme rather than a tailwind.config.js file.
