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 configurations for all storefront product images and thumbnails. It also contains product page, gallery widget configurations such as navigation options, fullscreen options and breakpoint conditions. |
/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 | Contains theme fonts and customized icons. |
/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>/<locale>/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>/
├── <Vendor>_<module>/
│ ├── web/
│ │ ├── css/
│ │ │ ├── source/
│ ├── layout/
│ │ ├── override/
│ ├── templates/
├── web/
│ ├── css/
│ │ ├── source/