Magento 2 Vendor Module and App/code Issues

We recently came across a recurring (and annoying) problem with some of our Magento 2 modules. The issue was that when ever composer install/update was called the module would be copied to app/code and thus cause class name conflicts with the canonical module in vendor.

The fix for this was hard to find and it turns out the Magento 2’s documentation needs updating.

To fix the problem, look to your module’s composer.json and find the extra field.

If it is present and contains a map directive like:

...

"extra": {
    "map": [
        [
            "*",
            "VendorName/ModuleName"
        ]
    ]
}
...

Then remove it, but ensure that your PSR-4 namespacing is set up correctly.

...
"autoload": {
        "files": [
            "registration.php"
        ],
        "psr-4": {
            "VendorName\\ModuleName\\": ""
        }
    }
...

See the following commit and composer.json for a full example