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/ | 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 it exists in the parent theme | This file contains configuration for all storefront product images and thumbnails. |
/i18n | optional | .csv files with translations. |
/media | optional | 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. The "name" field must be in the format "<vendor-name>/theme-<area>-<theme-name>". |
/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 title 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. |
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 storefront, 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/ 