What I wished someone had told me before starting a Magento 2 project

This is a list of gotchas that caught us out in our first Magento 2 projects…

Tip 1: Use developer and production deploy modes

Magento 2 is by default in default deployment mode, which is not very useful. There are three modes:

  1. default
  2. developer
  3. production

The main difference is that developer mode creates DI generation classes and static content on the fly as required and production mode does not. Default is somewhere in between as explained in the documentation and is neither fast enough for production nor gives enough exception information to be useful for development. So it should be changed early on by using the command:

php bin/magento deploy:mode:set developer

But… what about the principle of keeping development and production environments as similar as possible?

That’s a very good question that I’ve pretended you’ve asked, and unfortunately Magento 2 does not yet have a good answer. We have come across a number of examples in just a few months where features that worked in development mode have not worked in production mode – mostly DI errors, as when doing a static deployment for production all generated classes are created rather than just the subset that is created on demand when hitting pages.

The obvious answer to this is to use production mode when developing. However, that stops exceptions being shown to the screen. More importantly there is no on-the-fly static and DI compilation, so static deployments are required whenever you make a style change or one that affects DI. And in 2.1 deployments can take a long time – with 2 locales and 3 themes this can take easily take 30 minutes. That’s not going to lead to agile development.

So the compromise is:

Tip 1.1: Use Continuous Integration to catch differences in production

Obviously, automatic deployment and testing on a staging server should be under the assumption that all tests are passing on development, so before merging into development it would be best to change to production mode and test.

Tip 2: Themes are mobile first, so work that way

Many designers will be used to creating responsive themes by designing the desktop css and then tweaking for mobile. The problem is that Magento 2 works the other way (there are good reasons to) and this is reflected in the structure of the theme’s less files. Our advice would be to attempt progressive enhancement from mobile up and use the same break-points as Magento 2’s blank theme. Otherwise you’ll end up fighting with Magento 2’s default styling, end up replacing it, and have to recode everything from scratch.

Tip 3: RequireJS does not automatically wrap you in a document ready function

This may seem obvious, but when developing without using JS merging and bundling and without the added speed of static caching all your RequireJS code will probably run late enough so that this does not matter. Well, it will matter as soon as you move to production, so make sure you’re wrapping anything that needs to run post-DOM-ready in your favourite document-ready function, e.g.:

require(['jquery'], function($) {
    $(function() {
        ...your code for post-DOM...
About the author

Robert Egginton

As our chief problem-solver and systems architect, Rob is involved in every aspect of our development processes. Rob is partial to a bit of improvisational theatre, and setting up a smart home on a budget.