Awesome-omni-skill medusa-astro-storefront

Build blazing fast e-commerce storefronts using MedusaJS as headless backend and Astro for static-first rendering with React islands. Triggers on requests for MedusaJS frontends, Astro e-commerce, headless commerce with static generation, or performance-optimized storefronts.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/development/medusa-astro-storefront" ~/.claude/skills/diegosouzapw-awesome-omni-skill-medusa-astro-storefront && rm -rf "$T"

manifest: skills/development/medusa-astro-storefront/SKILL.md

source content

MedusaJS + Astro Storefront

Build e-commerce storefronts achieving sub-second LCP and 95+ Lighthouse scores through static generation with selective hydration.

Persona

You are a performance-obsessed e-commerce engineer specializing in static-first Astro sites with React islands. You prioritize Core Web Vitals, minimal JavaScript, and conversion-optimized UX. You use the MedusaJS SDK over raw fetch calls.

Commands

# Initialize
npm create astro@latest storefront -- --template minimal
cd storefront
npx astro add react tailwind
npm install @medusajs/js-sdk @tanstack/react-query nanostores @nanostores/react

# Development
npm run dev

# Build & Preview
npm run build
npm run preview

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Cloudflare Edge                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │ Static HTML │  │ Edge Cache  │  │ Image Transform │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────────────────────────────────────┐
│                    Astro Frontend                        │
│  ┌──────────────────────┐  ┌──────────────────────────┐ │
│  │ Static Pages (HTML)  │  │ React Islands (JS)       │ │
│  │ - Product pages      │  │ - Cart                   │ │
│  │ - Collection pages   │  │ - Search                 │ │
│  │ - Landing pages      │  │ - Checkout               │ │
│  │ - Blog/Content       │  │ - Quantity selectors     │ │
│  └──────────────────────┘  └──────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────────────────────────────────────┐
│                MedusaJS Backend (API)                    │
│  Products │ Cart │ Checkout │ Orders │ Customers        │
└─────────────────────────────────────────────────────────┘

Boundaries

Always Do

Use
```
@medusajs/js-sdk
```
over raw fetch calls
Use
```
client:visible
```
as default hydration directive for e-commerce islands
Use nanostores for cross-component state (cart, UI state)
Use
```
getStaticPaths()
```
for product/collection pages
Set
```
loading="eager"
```
+
```
fetchpriority="high"
```
only on LCP image
Format prices with
```
Intl.NumberFormat
```
(amounts are in cents)

Ask First

Adding new React islands (each adds JS weight)
Changing hydration directives
Adding client-side data fetching
Implementing checkout flow (complex, needs careful planning)

Never Do

Hydrate entire pages with React
Use React Context instead of nanostores
Fetch product data client-side for catalog pages
Use
```
client:load
```
for below-fold components
Skip
```
getStaticPaths()
```
for product pages

Island Hydration Directives

Directive	Use Case	Example
`client:load`	Critical above-fold interactivity	Search overlay
`client:visible`	Below-fold interactive elements	AddToCart, Reviews
`client:idle`	Non-critical features	Newsletter signup
`client:only="react"`	Browser-API dependent	Components using window

Default to

client:visible

for most e-commerce islands.

Key Principles

Static by default - Generate HTML at build time for all catalog pages
Hydrate sparingly - Only cart, search, and checkout need JavaScript
SDK over fetch - Use
```
@medusajs/js-sdk
```
for type safety and automatic retries
Nanostores for state - Lightweight, framework-agnostic state that works with Astro
Edge caching - Deploy to Cloudflare for global edge distribution
Images matter - Use
```
loading="eager"
```
only for LCP image, lazy load everything else

Environment Variables

MEDUSA_BACKEND_URL=http://localhost:9000
MEDUSA_PUBLISHABLE_KEY=pk_xxx

References

SDK setup and helpers:
```
references/medusa-sdk.md
```
Component implementations:
```
references/implementations.md
```
Performance optimization:
```
references/performance.md
```
Deployment config:
```
references/deployment.md
```
Original full guide:
```
references/SKILL.original.md
```