Storefront Best Practices

• Een e-commerce storefront bouwen of uitbreiden — elk framework (Next.js, SvelteKit, TanStack Start, React, Vue): productpagina's, productoverzichten, winkelwagen, afrekenen, navigatie, homepage, zoeken, accountpagina's of orderbevestiging.
• Een backend integreren (inclusief Medusa) — SDK-instelling, ophalen van producten/categorieën/regio's, prijsweergave, selectie van betaalmethoden en wagenbeheer.
• Een bestaande winkel optimaliseren — conversieratio's verbeteren, problemen met de mobiele ervaring oplossen, gestructureerde SEO-data toevoegen of de toegankelijkheid in het aankoopproces verbeteren.
• Een storefront-implementatie plannen — een stapsgewijs bouwplan genereren dat verwijst naar de juiste referentiebestanden en bekende valkuilen vermijdt voordat er code wordt geschreven.

• Niet-ecommerce projecten — beheerdashboards, SaaS-apps, blogs, of elke website zonder een winkel-/aankoopstroom hebben geen gebruik voor de patronen van deze vaardigheid.
• Puur backend- of API-werk — als u alleen werkt aan de server-side commerce-logica zonder betrokken frontend storefront-component, voegt deze vaardigheid weinig waarde toe.

Voordat er code wordt geschreven die een backend API of SDK aanroept, legt de skill een 5-stappen workflow op: pauzeer, raadpleeg de documentatie of MCP-server, verifieer de methode met de gebruiker, schrijf de code en controleer vervolgens op TypeScript-fouten. Dit voorkomt geraden methodenamen, verouderde voorbeelden en stille runtime-fouten.

De vaardigheid koppelt elke winkeltaak — afrekenen, productoverzicht, navigatie, SEO, mobiel, Medusa-integratie en meer — aan een specifiek referentiebestand (bijv. reference/layouts/checkout.md, reference/medusa.md). Het specificeert precies welke bestanden geladen moeten worden vóór de implementatie van elke functie, zodat patronen consistent worden toegepast.

Behandelt regels met grote impact die uniek zijn voor storefronts: aria-live="polite" op winkelwagentellingen voor schermlezers, env(safe-area-inset-bottom) voor iOS-plaktoetsen, minimale aanraakdoelen van 44px, verplicht loading="lazy" op productafbeeldingen onder de vouw, en het verbod op emoji's in de storefront-UI.

Biedt correcte dynamische routepatronen voor Next.js (App en Pages Router), SvelteKit, TanStack Start en Remix voor product- en categoriepagina's. Waarschuwt uitdrukkelijk tegen statische routes per item die niet schaalbaar zijn.

Behandelt Medusa SDK-initialisatie (publishable API-sleutel vereist), correcte prijsweergave (niet delen door 100), vereiste region_id bij het ophalen van producten, CORS-poortconventies (8000), Vite SSR-configuratie, het gebruik van @medusajs/types in plaats van aangepaste typen, en het wissen van de winkelwagenstate na het plaatsen van een bestelling.

Een gecategoriseerde lijst van meer dan 30 benoemde anti-patronen op het gebied van winkelwagen/navigatie, productbrowsing, afrekenen, mobiel gebruik, SEO, prestaties, ontwerpconsistentie en backend-integratie — elk geformuleerd als een concrete ❌ regel om te controleren vóór en tijdens de implementatie.

De skill biedt een sequentiële workflow van 10 stappen, van ontdekking (het laden van design.md) tot en met foundation, kerncomponenten, winkelflow en optimalisatie. Elke stap verwijst naar het exacte bestand dat geladen moet worden vóór de implementatie, zodat niets wordt overgeslagen en stijlen consistent blijven.

Begeleidt beslissingen over de checkout-architectuur (enkele pagina vs. meerdere stappen), dwingt het ophalen van betaalmethoden vanuit de backend af in plaats van deze hardgecodeerd op te nemen, markeert de vereiste voor gastafrekenen en biedt de Medusa-specifieke stappen voor betalingsintegratie via reference/layouts/checkout.md en reference/medusa.md.

Behandelt SDK-instelling, regio- en prijspatronen, het ophalen van producten met region_id, landenlijsten afgestemd op de regio van de winkelwagen, Vite SSR-configuratie, en het gebruik van de Medusa MCP-server voor methodeverificatie — ter voorkoming van de meest voorkomende integratiefouten bij Medusa-storefronts.

Verwijst ontwikkelaars naar reference/mobile-responsiveness.md voor touch-targetgroottes, veilige-zone-insets en afbeeldingsoptimalisatie, en naar reference/seo.md voor Product JSON-LD-schema, metatags, Open Graph en het meten van Core Web Vitals via PageSpeed Insights.