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 file). 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, 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/
Find us on