Magento 2 Frontend Development
Before writing code
Fetch live docs:
- Web-search
site:developer.adobe.com commerce frontend-core for frontend development guide
- Fetch
https://developer.adobe.com/commerce/frontend-core/guide/css/preprocess for CSS/LESS docs
- Web-search
site:developer.adobe.com commerce frontend-core guide layouts for layout XML reference
- Web-search
site:developer.adobe.com commerce frontend-core guide templates for template guide
Layout XML
How Layouts Work
Layout files map to route handles and define the page structure:
- Containers — structural wrappers (header, content, footer)
- Blocks — content-rendering units tied to PHP classes and templates
- Handle naming:
<route>_<controller>_<action>.xml (e.g., catalog_product_view.xml)
default.xml — applies to all pages
Key Layout Instructions
<referenceContainer> — modify an existing container
<referenceBlock> — modify an existing block
<block> — add a new block with class, template, name
<move> — relocate a block/container
<referenceBlock name="block_name" remove="true"/> — remove a block (or use <referenceContainer> for containers). Note: there is no standalone <remove> element for blocks; the remove="true" attribute is set on <referenceBlock> or <referenceContainer>.
<update> — include another layout handle
<arguments> — pass data to blocks
Layout Files Location
- Module:
view/frontend/layout/ or view/adminhtml/layout/
- Theme:
Magento_Module/layout/
Blocks and Templates
Block Classes
- Extend
Magento\Framework\View\Element\Template
- Contain data logic that templates consume
$block->someMethod() in PHTML templates
PHTML Templates
- Located in
view/frontend/templates/ or theme overrides
- PHP + HTML files with
.phtml extension
- Access block:
$block, escape output: $escaper->escapeHtml()
ViewModels (Recommended)
MVVM pattern — inject ViewModels into blocks via layout XML arguments:
- ViewModels implement
Magento\Framework\View\Element\Block\ArgumentInterface
- Keeps blocks thin; ViewModels carry the logic
- Access in template:
$viewModel = $block->getData('view_model');
JavaScript
RequireJS
- AMD module system — all JS loaded as modules
requirejs-config.js — maps module aliases, mixins, shims
- Located in
view/frontend/web/ or view/frontend/requirejs-config.js
KnockoutJS
- Two-way data binding for dynamic UI
- Used extensively in checkout and UI components
- Custom bindings via
ko.bindingHandlers
- HTML templates in
view/frontend/web/template/ (.html files)
JS Mixins
Extend existing JS modules without overriding:
- Declared in
requirejs-config.js under config.mixins
- Wrapper function receives original module and modifies it
jQuery Widgets
Custom widgets extend $.widget:
- Initialized via
data-mage-init attribute or <script type="text/x-magento-init">
- Configuration passed as JSON
Themes
Theme Structure
app/design/frontend/VendorName/theme-name/
├── etc/view.xml # Image sizes, responsive breakpoints
├── registration.php # Theme registration
├── theme.xml # Theme name, parent
├── composer.json
├── Magento_Module/ # Module overrides
│ ├── layout/ # Layout XML overrides
│ └── templates/ # Template overrides
├── web/
│ ├── css/source/ # LESS source files
│ ├── images/
│ └── js/
└── media/preview.jpg
Theme Inheritance
Themes declare a parent in theme.xml. Fallback chain: current theme → parent theme → module views → framework. Override files by placing them in the same relative path.
Hyva Themes (Modern Alternative)
Open source since late 2025. Replaces KnockoutJS + RequireJS + jQuery with Alpine.js + Tailwind CSS. Dramatically faster: ~5 requests vs ~230, ~0.4MB vs ~3MB page weight.
LESS/CSS
- Default preprocessor: LESS
@magento_import directive for theme fallback
- Variables in
_variables.less, overridden per theme
- Server-side compilation for production, client-side for development
Best Practices
- Use ViewModels instead of heavy block classes
- Override templates at the theme level, not module level (for customization)
- Use layout XML to add/move/remove blocks — avoid direct template editing of core
- Minimize JavaScript — prefer server-rendered HTML where possible
- Use
$escaper->escapeHtml(), escapeUrl(), escapeJs() for XSS prevention
- Consider Hyva for new projects — dramatically better performance
Fetch the frontend development guide for exact layout XML schema, template escaping methods, and RequireJS configuration patterns before implementing.
1---2name: magento-frontend3description: Build Magento 2 frontend — layout XML, blocks, PHTML templates, ViewModels, themes, JavaScript (RequireJS/KnockoutJS), and LESS/CSS. Use when customizing the storefront, building themes, or working with frontend components.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/magento-frontend7---89# Magento 2 Frontend Development1011## Before writing code1213**Fetch live docs**:141. Web-search `site:developer.adobe.com commerce frontend-core` for frontend development guide152. Fetch `https://developer.adobe.com/commerce/frontend-core/guide/css/preprocess` for CSS/LESS docs163. Web-search `site:developer.adobe.com commerce frontend-core guide layouts` for layout XML reference174. Web-search `site:developer.adobe.com commerce frontend-core guide templates` for template guide1819## Layout XML2021### How Layouts Work2223Layout files map to route handles and define the page structure:24- **Containers** — structural wrappers (header, content, footer)25- **Blocks** — content-rendering units tied to PHP classes and templates26- Handle naming: `<route>_<controller>_<action>.xml` (e.g., `catalog_product_view.xml`)27- `default.xml` — applies to all pages2829### Key Layout Instructions3031- `<referenceContainer>` — modify an existing container32- `<referenceBlock>` — modify an existing block33- `<block>` — add a new block with class, template, name34- `<move>` — relocate a block/container35- `<referenceBlock name="block_name" remove="true"/>` — remove a block (or use `<referenceContainer>` for containers). Note: there is no standalone `<remove>` element for blocks; the `remove="true"` attribute is set on `<referenceBlock>` or `<referenceContainer>`.36- `<update>` — include another layout handle37- `<arguments>` — pass data to blocks3839### Layout Files Location4041- Module: `view/frontend/layout/` or `view/adminhtml/layout/`42- Theme: `Magento_Module/layout/`4344## Blocks and Templates4546### Block Classes4748- Extend `Magento\Framework\View\Element\Template`49- Contain data logic that templates consume50- `$block->someMethod()` in PHTML templates5152### PHTML Templates5354- Located in `view/frontend/templates/` or theme overrides55- PHP + HTML files with `.phtml` extension56- Access block: `$block`, escape output: `$escaper->escapeHtml()`5758### ViewModels (Recommended)5960MVVM pattern — inject ViewModels into blocks via layout XML arguments:61- ViewModels implement `Magento\Framework\View\Element\Block\ArgumentInterface`62- Keeps blocks thin; ViewModels carry the logic63- Access in template: `$viewModel = $block->getData('view_model');`6465## JavaScript6667### RequireJS6869- AMD module system — all JS loaded as modules70- `requirejs-config.js` — maps module aliases, mixins, shims71- Located in `view/frontend/web/` or `view/frontend/requirejs-config.js`7273### KnockoutJS7475- Two-way data binding for dynamic UI76- Used extensively in checkout and UI components77- Custom bindings via `ko.bindingHandlers`78- HTML templates in `view/frontend/web/template/` (`.html` files)7980### JS Mixins8182Extend existing JS modules without overriding:83- Declared in `requirejs-config.js` under `config.mixins`84- Wrapper function receives original module and modifies it8586### jQuery Widgets8788Custom widgets extend `$.widget`:89- Initialized via `data-mage-init` attribute or `<script type="text/x-magento-init">`90- Configuration passed as JSON9192## Themes9394### Theme Structure9596```97app/design/frontend/VendorName/theme-name/98├── etc/view.xml # Image sizes, responsive breakpoints99├── registration.php # Theme registration100├── theme.xml # Theme name, parent101├── composer.json102├── Magento_Module/ # Module overrides103│ ├── layout/ # Layout XML overrides104│ └── templates/ # Template overrides105├── web/106│ ├── css/source/ # LESS source files107│ ├── images/108│ └── js/109└── media/preview.jpg110```111112### Theme Inheritance113114Themes declare a parent in `theme.xml`. Fallback chain: current theme → parent theme → module views → framework. Override files by placing them in the same relative path.115116### Hyva Themes (Modern Alternative)117118Open source since late 2025. Replaces KnockoutJS + RequireJS + jQuery with **Alpine.js + Tailwind CSS**. Dramatically faster: ~5 requests vs ~230, ~0.4MB vs ~3MB page weight.119120## LESS/CSS121122- Default preprocessor: LESS123- `@magento_import` directive for theme fallback124- Variables in `_variables.less`, overridden per theme125- Server-side compilation for production, client-side for development126127## Best Practices128129- Use ViewModels instead of heavy block classes130- Override templates at the theme level, not module level (for customization)131- Use layout XML to add/move/remove blocks — avoid direct template editing of core132- Minimize JavaScript — prefer server-rendered HTML where possible133- Use `$escaper->escapeHtml()`, `escapeUrl()`, `escapeJs()` for XSS prevention134- Consider Hyva for new projects — dramatically better performance135136Fetch the frontend development guide for exact layout XML schema, template escaping methods, and RequireJS configuration patterns before implementing.