Home >Magento 2 Directory and File Structure: A Kick-Ass Explanation

Magento 2 Directory and File Structure: A Kick-Ass Explanation

Hi guys, 

Today, I keep on providing a detailed explanation about Magento 2 Directory and File Structure. This helps developers to figure out how these structures work and develop Magento 2 extensions, themes and customize code effectively. 

Magento 2 Directory Structure

As mentioned in the previous article of Magento 2 Installation, there is a Magento 2 directory structure after you finish installing. Let’s take a look at this structure in the following image: 


I will explain each folder in detail so that you can get a better understanding of this structure. 


By default, there are 3 sub-directories included in this app folder such as design, i18n and etc

You can create the app/code directory which contains all custom modules.

You also had better store your custom store theme in the app/design/frontend directory and store admin themes in the app/design/adminhtml directory.

To store language packages, the app/i18n directory is your need to help you create a multi-language store. 

After installing Magento 2, you cannot see the app/code directory because it is not a default folder. Magento core modules are stored in the vendor directory to prevent the mixture between custom modules and Magento core modules to their Git repo. In case your packages are installed via Composer, they are stored in the vendor/. I don’t recommend you to follow this way because your changes are overridden when you upgrade Magento application.


Magento CLI executable script which activates Magento commands is included in this directory. They can be used to clear cache, reindex, upgrade and so on.


This directory includes automated functional tests that Magento Test Framework runs.


This directory contains all of Magento’s generated code.


The lib/ directory contains all Magento and vendor library files and non-module based Magento code. This is mostly a system code that aid Magento to run.


The Router.php file which is used to implement the PHP built-in server is stored in this folder. I don’t recommend this file because it contains tons of potentially big security holes.


An index.php file used to run the application in production mode and generated static files of your Magento theme are included in the pub/ directory. This directory provides a security measure in which public access to the root directory asset is restricted.


It includes Magento’s installation setup files.


 This folder contains raw cache files, logs, sessions, and reports.


This directory contains the framework core. You can store additional modules in this directory in case you install Magento 2 via Composer. It includes different packages defined under the composer.json file.

Module File Structure


Below is a typical file structure for a Magento 2 module:Magento-2-Module-File-Structure

Common directories

  • Block: includes module block classes
  • Controller: includes module controller classes 
  • etc: includes configuration files; in particular, module.xml (required).
  • Model: includes models and module resources.
  • Setup: includes classes for module database structure and data setup which are invoked when installing or upgrading.

Additional directories

You can insert additional folders for configuration and other ancillary functions such as plugin, localization, and layout files.

  • Api: includes PHP classes exposed to the API.
  • Console: includes CLI commands.
  • Cron: includes cron job definitions.
  • CustomerData: includes section files.
  • Helper: includes aggregated functionality.
  • i18n: includes localization files.
  • Observer: includes files to execute commands from the listener.
  • Plugin: includes any needed plugins.
  • UI: includes data generation files.
  • view: includes view files such as static view files, design templates, email templates, and layout files.
  • ViewModel: includes PHP model classes as part of a model-view-viewmodel (MVVM) implementation

*Note: The names of the folders are set by convention but not required, if you do not set as above, the code will run normally

Theme File Structure

Next, take a look at a typical theme file structure in the following:


Common directories

  • etc: includes configuration files such as the view.xml file which contains image configurations for all images and thumbnails.
  • i18n: Translation dictionaries.
  • media: Theme preview images (screen capture of your theme) can be put here.
  • web: Optional directory that contains static files organized into the following subdirectories:
    • css/source: includes a theme’s less configuration files that invoke mixins for global elements from the Magento UI library, and the theme.less file that overrides the default variables values.
    • css/source/lib: includes view files that override the UI library files stored in lib/web/css/source/lib.
    • fonts: The folder to place the different fonts for your theme.
    • images: Static images folder.
    • js: The folder for your JavaScript files.


Language Package File Structure

This is a typical directory structure for three language packages:


The top-level directory is a required directory for a language package. Besides, the directory name should be matched with the ISO code to detect the locale. 


I hope this article benefits all of you in your work when you need to build an extension, create a theme or make some code customization. If you have any questions, feel free to contact us or share your feedback in the comment section.

< Previous Post
Next Post >
+ posts