Define your configuration files
Each Magento 2 module
has its own set of configuration files, gathered into the module’s
Unlike Magento 1, there is no monolithic configuration file in Magento 2.
Root directory location
A component’s root directory matches the component’s name and contains all its subdirectories and files. Based on how you installed Magento, you can put your component’s root directory in one of two places:
<Magento install directory>/app: This is the recommended location for component development. You can set up this environment by Cloning the Magento 2 GitHub repository.
- For modules, use
- For storefront themes, use
- For Admin themes, use
- For language packages, use
- For modules, use
<Magento install directory>/vendor: You will find this location for installations that use the
composer create-projectto install the Magento 2 metapackage (which downloads the CE or EE code). You will also find this location if you install Magento by extracting the compressed Magento 2 archive.
Magento installs third-party components in the
vendor directory. But we recommend adding your components to the
app/code directory. If you put your component in the
vendor directory, Git will ignore it because Magento adds the
vendor directory to the
All components require these three files:
registration.php: This file registers your component with Magento. It uses the component’s root directory name as the component name. By default, the composer installs components in the
<Magento root dir>/vendordirectory. For more information, see Component registration.
etc/module.xml: This file defines basic information about the component, such as component dependencies and version number. Magento uses the version number to determine which schema and data to update when executing
composer.json: This file defines the dependencies that the component needs at runtime. For more information, see Composer integration.
Use /etc for your configuration files
Magento 2 looks for configuration information for each module in that module’s
etc directory. Depending on the needs of your module, you might have the following configuration files at the top level of your module’s
Additions you make to those configuration files are applied globally to your module.
In addition to those files, a Magento 2 module also has nested configuration directories in the
etc directory for any required administration html, frontend, API REST, or API SOAP specific configuration. Additions you make to files in these directories override the settings in the global configuration files for the respective functionality only. That is, if you add a
config.xml file to
etc/frontend, the settings you make in that file overrides the settings in
etc/config.xml for storefront
<your module root dir>/etc/adminhtml/
<your module root dir>/etc/frontend/
<your module root dir>/etc/webapi_rest/
<your module root dir>/etc/webapi_soap/
- Configuration files that are in the top level of that module’s
etcdirectory are global to that component.
- Configuration files placed in subdirectories (
webapi_soap) apply only to those respective functional areas.
Tailor your configuration files for what your module does
The exact set of configuration files required for your module depends on what your new module does. The required configuration files depend on how you plan to use the module: will the module be manifested on the storefront UI, or in the Magento Admin
panel, or as a backend
that makes a service call? Or all of the above. For example, if your module performs a function in the Admin, you should add any necessary configuration files for those functions to
<your module root dir>/etc/adminhtml/di.xml
<your module root dir>/etc/adminhtml/routes.xml
Similarly, if your module changes the UI, you should add the needed configuration files to
~/etc/frontend/. For example:
<your module root dir>/etc/frontend/di.xml
<your module root dir>/etc/frontend/page_types.xml
If the module is a service that may call an API, or does some other work that is not manifested in the UI you should add any needed configuration files in the REST and/or SOAP webapi configuration directories, like this:
<your module root dir>/etc/webapi_rest/di.xml
<your module root dir>/etc/webapi_soap/di.xml
Keep in mind that you might be able to handle your module’s configuration solely with configuration files at the top level of your module’s
etc directory, but the nested directory is a useful way to keep the configuration neatly compartmentalized.