Building a yStore Storefront
This guide helps you get oriented before you start writing code. yStore storefronts are built with Twig templates, Alpine.js reactivity, and SCSS for styling. Everything runs on Craft CMS.
How the pieces fit together
Request
└── Layout (global page skeleton)
└── Page template (route-level: catalog, cart, checkout, account)
└── Components (reusable feature units: product card, mini-cart)
└── Blocks (small fragments: totals row, popup shell)
Each layer overrides the one provided by yStore. You only override what you need — everything else falls through to the plugin's default templates.
What yStore gives you
| What | Where | Used for |
|---|---|---|
| Twig functions | craft.yui.* | Query products, get cart, format prices |
| Twig filters | Template filters | Format dates, prices, slugs |
window.yui object | Global JS | Cart ID, site context, utilities |
| Section data system | private-content-loaded event | Customer-specific data without full page reload |
| Alpine.js directives | x-defer | Lazy-load components for performance |
| JavaScript events | toggle-minicart-sidebar, etc. | Cross-component communication |
| GraphQL API | POST /api | Headless / fetch-driven interactions |
Recommended path for new developers
1. Understand the theme layers
Learn layouts → pages → components → blocks before you override anything.
2. Set up your theme
Override templates, work with Alpine.js, handle localization and accessibility.
3. Learn the Twig helpers
Twig functions for products, cart, customers, formatting, and URLs.
4. Add interactivity
window.yui, Alpine.js, section data, dispatch messages, fetch API.
5. Study real examples
Product listing, product details, newsletter, caching, performance.
6. Pre-launch checklist
Everything to verify before going live.
Common starting points
"I need to customize the product listing page"
→ Read Theme Architecture, then override yui/pages/catalog/products.twig
"I need to add custom data to the cart totals" → Read PHP Events → EVENT_MODIFY_CART_TOTALS
"I want to build a headless storefront"
→ Read GraphQL API — start with createGuestCart → addProductsToCart → checkout flow
"I need to add Alpine.js behavior to a template" → Read JavaScript & Alpine.js and Patterns
"I want to validate a custom form" → Read Form Validation
"My CSS does not override the cart/checkout styles" → Read Customizing Cart & Checkout — the plugin's stylesheets load after yours, so plain class selectors lose. The article explains all four ways around it.
Before building something from scratch, check Real-life Examples — product listing, product detail, and checkout flows are already documented with working code.