Cartridge path order for extended controllers and wildcard module requires
Key Takeaway
List your overlay cartridge first, plugin cartridges next, and app_storefront_base last. A wildcard require() returns the leftmost match, and module.superModule searches only to the right of the current cartridge.
A site's cartridge path is an ordered list of cartridges. When more than one cartridge has a file with the same name, the order decides which file runs. Developers stack custom cartridges on top of base cartridges such as app_storefront_base instead of editing them. The order of names in the path controls three things: which controller handles a request, which module a wildcard require() loads, and what module.superModule returns.
Left-to-right file lookup
The cartridge path controls file lookup for a site, so it defines what code runs. When a controller, script, model, or ISML template is called by URL or by code, B2C Commerce searches the cartridge path from left to right.
Customizations go in an overlay cartridge, so you never edit app_storefront_base or plugins such as plugin_applepay. Because those cartridges stay unchanged, you can keep getting security updates, bug fixes, and new features.
A typical layered path puts custom cartridges first and the base last, for example cartridge_A:cartridge_B:cartridge_C:cartridge_D:app_storefront_base.
To override a template, create a new cartridge with a template of the same name and relative path as the original. Because lookup runs left to right, the new cartridge must come before the original in the cartridge path.