M2M2: Theme development

Published on 23 Apr 2019 , edited on 26 Apr 2019

So with the server, installation, migration and first tests done, it’s time to start re-creating the theme and modules. At this point I have installed all needed modules already (though not configured yet) and I’m starting to create the front-end.

The process is a bit different then in M1, mostly due to the restructured codebase in filesystem and naming. From here on the process is less “A-to-B structured” so I’ll just note paragraphs of all things I run into.

Blank Theme inheritance

Creating a theme you’ll want to inherit the Magento base theme, called ‘Blank’. But to find which files to overwrite you’ll have to look in the vendor/magento/module-* folders.

Deploying changes

Working the front-end mostly means figuring out the correct workflow for deploying to actually publish and see/test your changes. I had some placeholder CSS in my custom theme in a few .less files, and later tried to install a module (and thus deploying the changes). What happened was the CSS render failed because invalid markup, and the front-end broke because it can’t render the CSS. So I fixed the invalid markup and ran

magento setup:upgrade && magento setup:static-content:deploy -f

But this takes a while to run for each simple CSS edit. SO!

Setup Grunt CLI

M2 has Grunt included to help with this kind of workflow; it enables us to swatch for changes in the .less files and render them on the go. We install nodejs and npm, then the grunt-cli globally. Copy the sample files to make use of them, also copy the themes.js to local-themes.js and add your custom theme info in there.

sudo apt-get install nodejs
sudo apt-get install npm
sudo npm install -g grunt-cli
cd <your magento root dir>
cp package.json.sample package.json
cp Gruntfile.js.sample Gruntfile.js
cp grunt-config.json.sample grunt-config.json
sudo cp dev/tools/grunt/configs/themes.js dev/tools/grunt/configs/local-themes.js
sudo nano dev/tools/grunt/configs/local-themes.js
npm install
npm upgrade

Watching for changes

It was a bitch to get Magento to behave like I’d expect in terms of rendering the CSS and not breaking the site with permission issues. I got a snippet ready that seems to fix most permission problems, and running setup:upgrade and setup:di:compile seems to work mostly.

To get grunt watch to work properly if you’re extending the blank theme via _extend.less and you want to include some seperate files for organisation like so;

// CSS structure, roughly following SMACSS architecture

// Reset
// Using normalize.css
@import '../_reset.less';

// Vars
// Centralize what you can in a variable
@import '../_vars.less';

// Layout
// Head structure of pages
@import '../_layout.less';

// Module blocks
// Styles for re-usable blocks
@import '../_blocks.less';

// Theme    
// Basically everything else
@import '../_theme.less';

You’ll have to edit <mage root>/dev/tools/grunt/config/local-themes.js (copy it over from themes.js), and include all parts plus the regular files of the parent theme in your custom theme definition;

    MyCompany: {
        area: 'frontend',
        name: 'MyCompany/MyTheme',
        locale: 'en_US',
        files: [
        dsl: 'less'

For it to properly pick up on these files you might need to run grunt exec first, so it’ll clean all paths and generate all map files needed for Less to work. After that just running grunt watch should pick up on any changes.


Just regular old rants and blogs.

All categories

All tags

All posts