magento-frontend git:20260309.786511cB

Immutable. This exact content is served forever at /api/v1/blob/1fd1dea87975f546.

---
name: magento-frontend
description: 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.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# Magento 2 Frontend Development

## Before writing code

**Fetch live docs**:
1. Web-search `site:developer.adobe.com commerce frontend-core` for frontend development guide
2. Fetch `https://developer.adobe.com/commerce/frontend-core/guide/css/preprocess` for CSS/LESS docs
3. Web-search `site:developer.adobe.com commerce frontend-core guide layouts` for layout XML reference
4. 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.