Module Configuration Files

Module configuration files

Required configuration files

Every module has its own set of configuration files, gathered into the module's etc directory. Unlike Magento 1, there is no monolithic configuration file — each module contributes its own XML files and the framework merges them at runtime.

Root directory location

Modules live under app/code/<Vendor>/<Module>/ (custom code) or under vendor/<vendor>/<module>/ when installed via Composer. Either way the etc/ directory is relative to the module root.

Top-level configuration files (global scope)

• etc/module.xml — declares the module name, version, and <sequence> dependencies on other modules (controls load order).
• etc/di.xml — dependency-injection configuration: preference, type, virtualType, plugin, sensitive config, and arguments.
• etc/config.xml — default configuration values for Stores > Configuration fields (the same paths you read via ScopeConfigInterface).
• etc/acl.xml — declares the tree of permission resources under Magento_Backend::admin for role-based access.
• etc/webapi.xml — REST / SOAP endpoint routes, HTTP methods, service class + method, and ACL resources.
• etc/crontab.xml — defines cron jobs, their schedule, and the PHP class/method to invoke.
• etc/events.xml — binds observer classes to named events (optionally scoped to frontend / adminhtml).
• etc/indexer.xml & etc/mview.xml — declare indexers and the mview change tracking triggers.
• etc/cache.xml — declare custom cache types.
• etc/extension_attributes.xml — declare extension attributes on service contract DTOs.
• etc/db_schema.xml & etc/db_schema_whitelist.json — declarative schema (replaces InstallSchema/UpgradeSchema).

Area-scoped subdirectories

Additions made in these subdirectories only apply inside that area and override the top-level equivalents for that area only:

Directory	Applies to
etc/frontend/	Storefront requests
etc/adminhtml/	Admin panel requests (routes.xml, menu.xml, system.xml, acl.xml, etc.)
etc/graphql/	GraphQL service
etc/webapi_rest/	REST web API
etc/webapi_soap/	SOAP web API

Minimum files for a working module

1app/code/Vendor/Module/
2├── registration.php
3├── etc/
4│   └── module.xml
5└── composer.json

A module is only enabled after registration.php runs and module.xml is present — enable it with bin/magento module:enable Vendor_Module && bin/magento setup:upgrade.

Dependency injection configuration (di.xml)

The di.xml file configures how the object manager wires dependencies. It is the single most important file for customizing Adobe Commerce behavior.

What you can do in di.xml

• <preference> — rewrite an interface-to-class binding (or one class to a subclass). Use sparingly — it's a hard rewrite and conflicts with other modules.
• <type> / <arguments> — override constructor arguments for a class, or inject a different service, or change an array argument.
• <virtualType> — create a named variant of an existing class with different dependencies, without writing a PHP subclass.
• <plugin> — register an around/before/after interceptor on a public method. This is the preferred customization mechanism.
• Sensitive / system-specific configuration — mark config paths as sensitive (CONFIG__DEFAULT__... env vars) or system-specific.

Example: preference

<preference for="Magento\Catalog\Api\ProductRepositoryInterface"
            type="Vendor\Module\Model\CustomProductRepository"/>

Example: constructor argument override

1<type name="Magento\Catalog\Model\Product">
2    <arguments>
3        <argument name="cacheLifetime" xsi:type="number">3600</argument>
4    </arguments>
5</type>

Example: virtual type

1<virtualType name="CustomLogger" type="Magento\Framework\Logger\Monolog">
2    <arguments>
3        <argument name="name" xsi:type="string">custom</argument>
4    </arguments>
5</virtualType>

Example: plugin

1<type name="Magento\Catalog\Model\Product">
2    <plugin name="vendor_module_price_adjust"
3            type="Vendor\Module\Plugin\ProductPlugin" sortOrder="10"/>
4</type>

Scope

Area scope rules: etc/di.xml applies globally. etc/frontend/di.xml applies only on the storefront, etc/adminhtml/di.xml only in the Admin, and so on — useful for providing a different plugin or preference per area.

Generated code

The object manager auto-generates Factory, Proxy, Interceptor, and ExtensionAttributesInterface classes into generated/code during bin/magento setup:di:compile. In production mode you must compile — the DI system will not generate at runtime.