Define your configuration files

Root directory location

A component’s root directory is the top-level directory for that component under which its folders and files are located. Depending on how your Magento development environment was installed, your component’s root directory can be located in two places:

• <Magento install directory>/app: This is the recommended location for component development. You can easily set up this type of environment by Cloning the Magento 2 GitHub repository.

  • For modules, use app/code.
  • For storefront themes, use app/design/frontend.
  • For Admin themes, use app/design/adminhtml.
  • For language packages, use app/i18n.

• <Magento install directory>/vendor: This location is found in the alternative setups where the composer create-project command was used to get a Magento 2 metapackage (which downloads the CE or EE code), or a compressed Magento 2 archive was extracted in order to install Magento.

  Any third party components (and the Magento application itself) are downloaded and stored under the vendor directory. If you are using Git to manage project, this directory is typically added to the .gitignore file. Therefore, we recommend you do your customization work in app/code, not vendor.

Required files

The following files are required for all components:

• registration.php: Among other things, this file specifies the directory in which the component is installed by vendors in production environments. By default, composer automatically installs components in the <Magento root dir>/vendor directory. For more information, see Component registration.
• etc/module.xml: This file specifies basic information about the component such as the components dependencies and its version number. This version number is used to determine schema and data updates when bin/magento setup:upgrade is run.
• composer.json: Specifies component dependencies and other metadata. 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 etc directory:

• acl.xml
• config.xml
• di.xml
• module.xml
• webapi.xml

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 functionality only.

• <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

• Configuration files that are in the top level of that module’s etc directory are global to that component.
• Configuration files placed in subdirectories (adminhtml, frontend, webapi_rest, 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 extension 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 etc/adminhtml/, like:

• <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.

Next

Create your component file structure