Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 42 ยท Requests and Output

The Theme System and Frontend Assets

Learn how Magento themes inherit from parents, how template and asset fallback works, what LESS and requirejs-config.js do, and how static content is deployed.

A Magento storefront looks the way it does because of a theme. A theme is a folder of templates, layout files, styles, images and scripts that sits on top of the modules. The clever part is that a theme does not have to copy everything: it names a parent, and Magento looks for each file in the theme first, then its parent, and so on, until a file is found. You change only what you need, and the rest keeps coming from the parent and the modules.

In this lesson you will meet the structure of a theme, the fallback rules for templates and assets, the role of LESS and requirejs-config.js, and the commands that turn all of it into files a browser can load. Magento does not run on this site, so the real files are read-only; two runnable stand-ins model the fallback lookup and the JavaScript configuration merge. Details differ between Magento versions and between themes, so check the code of your own installation before relying on a path.

What a theme looks like

Themes for the storefront live in app/design/frontend/<Vendor>/<theme>/ (or in vendor/ when installed through Composer). A small theme looks like this:

TEXT
app/design/frontend/Acme/shop/
โ”œโ”€โ”€ registration.php
โ”œโ”€โ”€ theme.xml
โ”œโ”€โ”€ composer.json
โ”œโ”€โ”€ etc/
โ”‚   โ””โ”€โ”€ view.xml
โ”œโ”€โ”€ media/
โ”‚   โ””โ”€โ”€ preview.jpg
โ”œโ”€โ”€ web/
โ”‚   โ”œโ”€โ”€ css/source/_extend.less
โ”‚   โ””โ”€โ”€ images/logo.svg
โ”œโ”€โ”€ Magento_Catalog/
โ”‚   โ”œโ”€โ”€ layout/catalog_product_view.xml
โ”‚   โ””โ”€โ”€ templates/product/view.phtml
โ””โ”€โ”€ Magento_Theme/
    โ””โ”€โ”€ layout/default.xml

Folders named after a module (Magento_Catalog) hold overrides for that module's layout files and templates. The top-level web folder holds assets for the theme itself.

registration.php registers the theme with Magento, much like a module registers itself (Your First Module):

PHP
<?php

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/Acme/shop',
    __DIR__
);

theme.xml describes it and names the parent:

XML
<?xml version="1.0"?>
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Acme Shop</title>
    <parent>Magento/luma</parent>
    <media>
        <preview_image>media/preview.jpg</preview_image>
    </media>
</theme>

The parent uses the form Vendor/themename. Magento ships a bare-bones theme called Magento/blank and Magento/luma, which extends it. Most custom themes extend one of the two. After you register a theme, you choose it per store view in the admin or through configuration.

Fallback: how a file is found

When a layout asks for the template Magento_Catalog::product/view.phtml, Magento searches in a fixed order and uses the first match. For a storefront theme with parents, the order is roughly:

  1. The theme: <theme>/Magento_Catalog/templates/product/view.phtml
  2. Each parent theme in turn, up the chain
  3. The module itself: view/frontend/templates/product/view.phtml
  4. The module's shared view/base/templates/ folder

Layout files follow the same idea, but they are merged rather than replaced, as shown in Layout XML and Handles. Static assets such as CSS, images and JavaScript use the fallback chain too, with a few more places to look, including the theme's web folder and library files shipped with the core. Assets can also be locale-specific.

Two rules of thumb follow from this:

  • Override as little as possible. Copying a template into your theme freezes it. When the module changes the original in an upgrade, your copy does not get the fix. Prefer layout changes (add, move or remove blocks), ViewModels and arguments before copying templates.
  • Child themes inherit from the parent's version. Overriding a file in Acme/shop wins over the same file in Magento/luma, but pages you did not touch continue to come from Luma and the modules.
flowchart TD
    A["Request: Magento_Catalog::product/view.phtml"] --> B{"In Acme/shop?"}
    B -->|"yes"| Z["Use it"]
    B -->|"no"| C{"In parent Magento/luma?"}
    C -->|"yes"| Z
    C -->|"no"| D{"In grandparent Magento/blank?"}
    D -->|"yes"| Z
    D -->|"no"| E["Module view/frontend/templates<br/>then view/base"]
    E --> Z

Fallback walks from the theme through its parents and finally to the module, using the first file it finds.

Luma, Blank and Hyvรค at a glance

Be careful with claims here, because this is the area that changes fastest:

  • Magento/blank is a minimal base theme. It exists mainly as a parent.
  • Magento/luma is the sample storefront theme that ships with Magento Open Source. It uses LESS for styles and a JavaScript stack built on RequireJS, jQuery and Knockout.
  • Hyvรค is a third-party theme and module ecosystem that replaces the Luma-era frontend stack with Tailwind CSS and Alpine.js to produce much lighter pages. It is not part of Magento itself, and extensions written for Luma's JavaScript often need a compatibility module to work with it. If you plan to use it, check its current documentation and licensing.

For a Luma-based or Blank-based theme, you can rely on the structures in this lesson. For another frontend, read that frontend's own documentation.

LESS and styles

Luma-style themes write styles in LESS, a CSS preprocessor, split into many small files so themes and modules can add to them. A theme usually does not rewrite the main stylesheets. It adds or overrides variables and appends rules in designated extension files, such as web/css/source/_extend.less, and Magento combines everything into the final CSS files. Variables like colors and font sizes live in web/css/source/_variables.less-style files in the base themes, which makes a rebrand mostly a matter of overriding values.

In developer mode, Magento can compile LESS on request. In production mode, styles must already be compiled, which is part of static content deployment, below.

requirejs-config.js

Storefront JavaScript is loaded with RequireJS, a module loader. Each module may provide view/frontend/requirejs-config.js, and Magento merges all of these files into one configuration:

JavaScript
var config = {
    map: {
        '*': {
            acmeGreeting: 'Acme_Hello/js/greeting'
        }
    },
    paths: {
        'acme/chart': 'Acme_Hello/js/vendor/chart.min'
    },
    config: {
        mixins: {
            'Magento_Catalog/js/product/list/toolbar': {
                'Acme_Hello/js/toolbar-mixin': true
            }
        }
    }
};

map creates aliases (here acmeGreeting points to a module's file), paths names file locations, and config.mixins lets you wrap an existing JavaScript component without editing it, similar in spirit to a plugin on the PHP side. Because configuration from all modules is combined, two modules that set the same key can conflict, so choose distinctive alias names.

Static content deployment

Browsers cannot read .phtml or .less files, and they should not fetch from app/code anyway. Public assets are served from pub/static/. In production mode you generate them with:

Terminal
bin/magento setup:static-content:deploy -f en_US

The command compiles LESS, merges the RequireJS configuration, and copies or symlinks each file to a path under pub/static/frontend/<Vendor>/<theme>/<locale>/. You can limit it to some themes, areas or locales with options (run it with --help to see the ones in your version). The exact flags and the point in a deployment at which you run them are covered in Deployment and Upgrades.

Some practical points:

  • In developer mode, files are generated or linked on demand, so you rarely need the command while coding.
  • After changing a template, layout or JavaScript in production mode, you must clean caches and deploy static content again to see the change.
  • If a page loads without styles or with 404s for JavaScript, a missing or stale pub/static deployment is the first thing to check.
  • Magento puts a version string in static URLs, which changes with each deploy. This makes browser caching safe.

Try it: a fallback resolver

This stand-in has a virtual file system (a list of paths) and finds a template by walking a theme chain. The chain comes from theme.xml-style parent declarations. It resolves only templates, ignores locales and area base details beyond a simple last step, and is far simpler than Magento's resolver, but the order of the search matches what you just read.

PHP Resolving a template through theme fallback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The first lookup stops at the theme itself. The cart template is found in Luma's folder, not in the module, because Luma overrides it. The product list falls through every theme to the module. A parent theme's override is never seen by a child that is not based on it.

Try it: merging requirejs-config files

Here is a simplified model of how module configurations combine. Real RequireJS handles map, paths, shim, config and more, and merges them by its own rules; this stand-in just merges nested arrays so later modules win on conflicting keys, enough to see why distinctive names matter.

PHP Combining module JavaScript configuration

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Both Acme_Hello and Other_Widget defined acmeGreeting, and the later module quietly won. In a real store this kind of clash is a classic source of confusing JavaScript bugs, which is why alias names should carry your vendor name.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the parent node in theme.xml do?

    The parent gives the fallback chain. Files missing in the child theme are looked up in the parent, then its parents, then the modules.
  2. 2. A template exists only in the module and in Magento/luma's folder. Your theme Acme/shop has Luma as its parent and no copy. Which file is used?

    The search goes theme, then parent themes, then the module. Luma's override comes before the module's original.
  3. 3. When must you run setup:static-content:deploy?

    Production mode serves pre-generated files from pub/static. Developer mode creates or links them on demand.
  4. 4. Why is copying a core template into your theme risky?

    An overriding copy shadows the original forever. Prefer layout changes and ViewModels where possible.

Summary

  • A theme is registered with registration.php, described by theme.xml, and extends a parent theme such as Magento/luma.
  • Templates and assets are found by walking from the theme through its parents to the module, using the first match.
  • Layout files merge; templates and most assets are replaced when the theme overrides them. Override as little as you can.
  • Luma-style themes use LESS and a RequireJS configuration merged from each module's requirejs-config.js. Hyvรค is a separate third-party approach with Tailwind CSS and Alpine.js.
  • bin/magento setup:static-content:deploy generates public assets for production mode, and caches must be cleaned after changes.

Next, see how the admin builds its grids and forms in UI Components Overview.