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
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
Each theme must be stored in a separate directory:
app/design/frontend/<Vendor>/ ├── <theme1> ├── <theme2>/ ├── <theme3> ├--...
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.
||optional||Module-specific styles, layouts, and templates.|
Module-specific styles (
||optional||Layout files which extend the default module or parent theme layouts.|
||optional||Layouts that override the default module layouts.|
||optional||Layouts that override the parent theme layouts for the module.|
||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.|
||required for a theme, but optional if it exists in the parent theme||This file contains configuration for all storefront product images and thumbnails.|
||optional||.csv files with translations.|
||required||This directory contains a theme preview (a screenshot of your theme).|
||optional||Static files that can be loaded directly from the frontend.|
||optional||This directory contains theme
View files that override the UI library files stored in
||optional||Images that are used in this theme.|
||optional||Describes the theme dependencies and some meta-information. Will be here if your theme is a Composer package.|
||required||Required to register your theme in the system.|
||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, if the theme is inherited from an existing theme. The file is used by the Magento system to recognize the theme.|
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 storefront, are distinguished as public theme files.
To be actually accessible for browsers public static files are published to the
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/