Showing results for 
Search instead for 
Did you mean: 

Migration Made Easy: 8 Best Practices for Extension Developers

Senior Member

Extensions are essential to the everyday operations of a Magento store; and we love the developers who work so hard to bring them to life. Extension migration is an equally important aspect of this process, and a vital consideration when merchants are adopting or upgrading to Magento 2. Extension developers can help merchants migrate effectively (and differentiate themselves in the market) by following 8 best practices.


The following summarize our shared understanding of what merchants and integrators expect from extension developers when planning a migration. While Magento is not explicitly enforcing any of these best practices at this time, we are actively encouraging you to implement these ideas into your development process.


It is in everyone's best interest to provide the best upgrade experience for our customers.


  1. Extension Availability

Occasionally, merchants cannot find a comparable version of their Magento 1 extension that is compatible with Magento 2. This is a frustration we all want to try and avoid, so the first priority is to ensure that merchants have what they need. Therefore, we encourage all developers with extensions on Magento 1 to migrate them to Magento 2. Not sure how? The migration process is detailed here.


  1. Extension functionality

Merchants and integrators sometimes find the Magento 2 version of an extension provides more limited functionality than the Magento 1 version. Often this is because core improvements in Magento 2 now provide the specific functionality. Merchants should always be made aware of functional differences between Magento 1 and Magento 2. Clearly explaining the differences between extension versions will help set expectations and avoid unpleasant surprises for merchants.


  1. Documentation

The more merchants know the better. Always provide technical documentation for your extension clearly detailing tables and fields used by your extensions, as well as locations of any assets or images saved to the disk. Include detailed documentation on how to migrate this content between versions. When content recreation is not easily imported, please document how to recreate it or any manual steps that need to be executed.


  1. Migrating extension code

Magento offers a Code Migration Toolkit that can assist with proof of concept migration of your existing extension code to Magento 2. Please realize that you will need to modify the extension to ensure it works properly in Magento 2. Many developers have found it easier, and more effective, to use this opportunity to rewrite their extensions, clean up the code, improve the architecture, and future-proof their work.


  1. Data migration mapping

It is possible to migrate data without needing to modify the Data Migration Tool. If the extension retains the same tables structure and data format as it has for Magento 1, then the tool will see no difference and simply transfer data. If not, the migration will interrupt and provide notification of the differences. The extension developer will need to provide mapping, configuration and transformation files for the Magento Data Migration Tool so the merchant or their integrator can use it to move custom data to the Magento 2 schema. You can find more information about customizing the Magento Data Migration Tool in DevDocs. (,


  1. Performance

Always make sure to test your tools/mapping/upgrade process on large data sets. Examples are available here as Large or Extra Large profiles. Data sets can be generated using Magento performance testing tools.


Ensure downtime is minimized during migration. This may involve migrations scripts that split data processing into several streams.


  1. Error Messages

When tools are unable to migrate or upgrade the data, provide clear logging, error messages, and explanations of what went wrong.


  1. Custom tooling

Last but not least, if your migration requirements cannot be fulfilled by the Data Migration Tool, it’s recommended that you provide custom tools to help migrate data/assets.



1 Comment