Cartridge path resolution with module.superModule and require paths
Key Takeaway
B2C Commerce uses the first matching file it finds on the cartridge path, searching from left to right. An overlay controller that extends a base controller with module.superModule runs only when the overlay cartridge sits to the left of the base cartridge.
A site's cartridge path is the ordered list of its cartridges. B2C Commerce searches it to decide which controller, script, model or ISML template to use. The require() function and the module.superModule property let you choose which copy of a module to load. With them, an overlay cartridge can reuse and extend base code such as app_storefront_base without editing it.
How the cartridge path decides what runs
The cartridge path is the ordered list of cartridges for a site. The order of the cartridges decides what code runs. When a URL or code calls a controller, script, model or ISML template, B2C Commerce searches the cartridge path from left to right and uses the first match. For example, an ISML template overrides a template with the same name and relative path in a cartridge later in the path.
A site has the cartridge path app_custom_shop:app_storefront_base. Both cartridges have a template with the same name at the same relative path, home/homePage.isml. When the site renders that template, B2C Commerce checks app_custom_shop first and finds a match there. The site shows the app_custom_shop version, and the app_storefront_base version is overridden.
For a URL request, B2C Commerce takes the first matching controller file on the cartridge path. B2C Commerce doesn't check whether that file contains the function named in the URL. Calling a function that doesn't exist causes an error.