Magento theme structure

What's in this topic

A design theme is an important part of the Magento application. This topic describes the file structure of a Magento theme.

Magento theme location

Storefront themes are conventionally located under app/design/frontend/<Vendor>/. Though technically they can reside in other directories. For example Magento built-in themes can be located under vendor/magento/theme-frontend-<theme_code> when a Magento instance is deployed from the Composer repository.

Each theme must be stored in a separate directory:

app/design/frontend/<Vendor>/
├── <theme1>
├── <theme2>/
├── <theme3>
├--...

Theme components

The structure of a Magento theme directory typically would be like following:

<theme_dir>/
├── <Vendor>_<Module>/ 
│	├── web/
│	│	├── css/
│	│	│	├── source/
│	├── layout/
│	│	├── override/
│	├── templates/
├── etc/
├── i18n/ 
├── media/
├── web/
│	├── css/
│	│	├── source/ 
│	├── fonts/
│	├── images/
│	├── js/
├── composer.json 
├── registration.php 
├── theme.xml 

Let’s have a closer look at each particular sub-directory.

The directories and files structure described below is the most extended one. It may not coincide with the structure of your store.

Directory Required Description
/<Vendor>_<Module> optional Module-specific styles, layouts, and templates.
/<Vendor>_<Module>/web/css/source optional Module-specific styles (.css and/or .less files). General styles for the module are in the _module.less file, and styles for widgets are in _widgets.less.
/<Vendor>_<Module>/layout optional Layout files which extend the default module or parent theme layouts.
/<Vendor>_<Module>/layout/override/base optional Layouts that override the default module layouts.
/<Vendor>_<Module>/layout/override/<parent_theme> optional Layouts that override the parent theme layouts for the module.
/<Vendor>_<Module>/templates optional This directory contains theme templates which override the default module templates or parent theme templates for this module. Custom templates are also stored in this directory.
/etc/view.xml required for a theme, but optional if exists in the parent theme This file contains images configuration for all storefront product images and thumbnails.
/i18n optional .csv files with translations.
/media required This directory contains a theme preview (a screenshot of your theme).
/web optional Static files that can be loaded directly from the frontend.
/web/css/source optional This directory contains theme less configuration files that invoke mixins for global elements from the Magento UI library, and theme.less file which overrides the default variables values.
/web/css/source/lib optional View files that override the UI library files stored in lib/web/css/source/lib
/web/fonts optional Theme fonts.
/web/images optional Images that are used in this theme.
/web/js optional Theme JavaScript files.
/composer.json optional Describes the theme dependencies and some meta-information. Will be here if your theme is a Composer package.
/registration.php required Required to register your theme in the system.
/theme.xml required The file is mandatory as it declares a theme as a system component. It contains the basic meta-information, like the theme name and the parent theme name, is the theme is inherited from an existing theme. The file is used by the Magento system to recognize the theme.

Theme files

Apart from the configuration file and theme metadata file, all theme files fall into the following two categories:

  • Static view files
  • Dynamic view files

Static view files

A set of theme files that are returned by the server to a browser as is, without any processing, are called the static files of a theme.

Static files can be located in a theme directory as follows:

<theme_dir>/
├── media/
├── web
│	├── css/ (except the "source" sub-directory)
│	├── fonts/
│	├── images/
│	├── js/

The key difference between static files and other theme files is that static files appear on a web page as references to the files, while other theme files take part in the page generation, but are not explicitly referenced on a web page as files.

Static view files that can be accessed by a direct link from the store front, are distinguished as public theme files.

To be actually accessible for browsers public static files are published to the /pub/static/frontend/<Vendor>/<theme>/<language>/css/ directory.

Dynamic view files

View files that are processed or executed by the server in order to provide result to the client. These are: .less files, templates, and layouts.

Dynamic view files are located in a theme directory as follows:

<theme_dir>/
├── Magento_<module>/ 
│	├── web/
│	│	├── css/
│	│	│	├── source/
│	├── layout/
│	│	├── override/
│	├── templates/
├── web/
│	├── css/
│	│	├── source/