Storefront Best Practices
Ship checkout, cart, product, and navigation patterns that convert—whether you wire them to Medusa or another commerce backend.
Overview
Storefront Best Practices is an agent skill most often used in Build (also Ship checkout flows, Launch SEO) that patterns modern ecommerce storefronts and Medusa-style backend integration.
Install
npx skills add https://github.com/medusajs/medusa-agent-skills --skill storefront-best-practicesWhat is this skill?
- Framework-agnostic guidance for Next.js, SvelteKit, TanStack Start, React, and Vue storefronts
- Decision frameworks for checkout, cart, payments, shipping, and order placement
- Medusa backend integration patterns—SDK setup, cart, products, and payment hooks
- SEO, mobile responsiveness, and conversion-oriented UI/UX patterns for shopping sites
- Applies to any storefront component—from homepage and search to account pages
Adoption & trust: 2.2k installs on skills.sh; 185 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are building or changing a store UI and need proven checkout, cart, and catalog patterns instead of guessing layout, payments, and API wiring.
Who is it for?
Indie builders implementing or improving online stores, especially with Medusa or similar headless commerce APIs.
Skip if: Pure backend-only catalog admin, non-commerce marketing sites with no cart/checkout, or teams that already enforce a locked internal design system with zero storefront changes.
When should I use this skill?
ALWAYS when working on ecommerce storefronts, checkout, cart, payment flows, product pages, Medusa backend integration, or any shopping-site component.
What do I get? / Deliverables
Your agent applies consistent storefront architecture, integration guidance, and UX/SEO patterns across every shopping component you touch.
- Component and flow patterns for cart, checkout, and catalog pages
- Backend integration guidance aligned to your commerce API
- SEO- and mobile-aware layout recommendations
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Storefront work is where shoppers see and buy; this skill anchors on building the customer-facing UI and flows that define the product experience. Checkout, cart, PDPs, and layout patterns are frontend-heavy surfaces, even when they call commerce APIs behind the scenes.
Where it fits
Scaffold a cart drawer and checkout steps with consistent state handling before wiring payment providers.
Configure Medusa SDK calls for products, regions, and payment sessions without ad-hoc API guesses.
Walk through payment and shipping edge cases before you open checkout to real customers.
Apply listing and PDP SEO patterns when product URLs and metadata go live.
Align homepage and collection layouts with merchandising updates without breaking cart flows.
How it compares
Use for opinionated ecommerce storefront patterns—not generic landing-page aesthetics skills or raw payment-gateway docs alone.
Common Questions / FAQ
Who is storefront-best-practices for?
Solo and indie developers shipping or refactoring ecommerce storefronts who want agent-guided patterns for cart, checkout, product pages, and backend hooks.
When should I use storefront-best-practices?
During Build when you implement cart, checkout, or product UI; during Build integrations when you connect Medusa or commerce APIs; and during Launch when you tune SEO and mobile shopping experiences.
Is storefront-best-practices safe to install?
Review the Security Audits panel on this Prism page and your org policy before installing any third-party skill; the skill guides code patterns and does not by itself grant network or secret access.
SKILL.md
READMESKILL.md - Storefront Best Practices
# Ecommerce Storefront Best Practices Comprehensive guidance for building modern, high-converting ecommerce storefronts covering UI/UX patterns, component design, layout structures, SEO optimization, and mobile responsiveness. ## When to Apply **ALWAYS load this skill when working on ANY storefront task:** - **Adding checkout page/flow** - Payment, shipping, order placement - **Implementing cart** - Cart page, cart popup, add to cart functionality - **Building product pages** - Product details, product listings, product grids - **Creating navigation** - Navbar, megamenu, footer, mobile menu - **Integrating Medusa backend** - SDK setup, cart, products, payment - **Any storefront component** - Homepage, search, filters, account pages - Building new ecommerce storefronts from scratch - Improving existing shopping experiences and conversion rates - Optimizing for usability, accessibility, and SEO - Designing mobile-responsive ecommerce experiences **Example prompts that should trigger this skill:** - "Add a checkout page" - "Implement shopping cart" - "Create product listing page" - "Connect to Medusa backend" - "Add navigation menu" - "Build homepage for store" ## CRITICAL: Load Reference Files When Needed **⚠️ ALWAYS load `reference/design.md` BEFORE creating ANY UI component** - Discovers existing design tokens (colors, fonts, spacing, patterns) - Prevents introducing inconsistent styles - Provides guardrails for maintaining brand consistency - **Required for every component, not just new storefronts** **Load these references based on what you're implementing:** - **Starting a new storefront?** → MUST load `reference/design.md` first to discover user preferences - **Connecting to backend API?** → MUST load `reference/connecting-to-backend.md` first - **Connecting to Medusa backend?** → MUST load `reference/medusa.md` for SDK setup, pricing, regions, and Medusa patterns - **Implementing homepage?** → MUST load `reference/components/navbar.md`, `reference/components/hero.md`, `reference/components/footer.md`, and `reference/layouts/home-page.md` - **Implementing navigation?** → MUST load `reference/components/navbar.md` and optionally `reference/components/megamenu.md` - **Building product listing?** → MUST load `reference/layouts/product-listing.md` first - **Building product details?** → MUST load `reference/layouts/product-details.md` first - **Implementing checkout?** → MUST load `reference/layouts/checkout.md` first - **Optimizing for SEO?** → MUST load `reference/seo.md` first - **Optimizing for mobile?** → MUST load `reference/mobile-responsiveness.md` first **Minimum requirement:** Load at least 1-2 reference files relevant to your specific task before implementing. ## Planning and Implementation Workflow **IMPORTANT: If you create a plan for implementing storefront features, include the following in your plan:** When implementing each component, page, layout, or feature in the plan: 1. **Refer back to this skill** before starting implementation 2. **Load relevant reference files** listed above for the specific component/page you're building 3. **Follow the patterns and guidance** in the reference files 4. **Check common mistakes** sections to avoid known pitfalls **Example plan structure:** ``` Task 1: Implement Navigation - Load reference/components/navbar.md - Follow patterns from navbar.md (dynamic category fetching, cart visibility, etc