During the last Firegento Hackathon in Paderborn, I worked in a group that concentrated on the improvements in Magento 2’s frontend. Even though an extensive documentation is available, we had our troubles to get started. In order to make it easier to get started with frontend development in Magento 2 in the future, this post shows a step by step guide on how to set up a frontend workflow – and how to avoid possible stumbling blocks that we experienced at the hackathon.

This blog post will not inform about how the frontend mechanisms of Magento 2 work in particular. Instead, it’s supposed to be a help for frontend developers who are – like me – in a transition phase, and who are now asked to create a working initial state.

Since there are already different variants and pitfalls during the installation, I recommend to first read our blogpost about Magento 2 installation and do the installation accordingly.

Please remember to activate the Developer Mode. Magento 2 should never be run in the Default Mode, which is a hybrid mode that isn’t helpful to anyone really. For further information on modes, take a look at the documentation, or again visit Alan Storm’s blog.

We can now open our browser and take a look at the frontend with it’s shiny Luma theme.

Project’s General Structure

The installation type we chose – “Integrator/Packager” – has all the advantages of Composer. As it’s typical for Composer, all Magento modules are stored in

Your own modules or themes can be added in two ways:

  1. via composer in the vendor folder
  2. via the classic approach in the folders app/code and app/design respectively

Set up Grunt Environment

When the installation is finished, the next step is to setup the Grunt environment. All described steps are covered in the official Magento 2 documentation, although there it’s not as compactly summarised as it is here.

First of all, we need node.js for our stack.

Then we can install the Grunt CLI

followed by the initialisation of the project specific dependencies

To test if everything is correctly installed, use the following call:

Create Theme Files and use them in Magento 2

In Magento 2, themes are stored in the file system in the following pattern:


For a minimal setup, we create a theme which inherits everything from Luma. So we create the following files:

Two trivia we want to change right now, so that we can see right away that we no longer use the original Luma theme:

Then we select the theme in Magento 2’s backend:

Stores > Configuration > Design > Design Theme

Start the Frontend Workflow with Grunt

Before we can really get to work, we need to tell Grunt that we have just created a new theme. And here is the file entry that does the trick:

Afterwards, the following steps should be executed exactly once before starting to work:

  1. Clean static files and caches:
  2. Collect resources and generate static files for our theme:
  3. Initialise the preprocessing:
  4. Afterwards, reload the frontend page!

The first page view might lead to excessively long load times, since Magento 2 starts the preprocessing in the background which means that a great number of files need to be processed.

Voilà! We have successfully changed Magento’s background color and font color in the menu using our own workflow.
From now on, we can start the watch task:

If we change a LESS file, Grunt will automatically update all necessary files so we only have to reload the frontend (with the LiveReload browser plugin installed, you won’t even need to do that manually).

Questions regarding the Magento 2 Frontend Development

Getting started with the development of Magento 2’s frontend can raise many questions: Why have we changed this LESS file in particular? What kind of strange variables are those? What shall I do with all this now? Answering all these questions would go way beyond the scope of this blog post. If you have a concrete question, you are welcome to leave a comment and I’ll do my best to answer them or maybe even write another blog post.

We are all fairly new to working with Magento 2. The templating and preprocessing system, introduced by Magento 2, with its own LESS library is very complex. Even while writing these lines, I am still busy to grasp all background information and dependencies to the full extent. For a better start I highly recommend to study the official documentation.

There is also a documentation of the structure, content, coding standards, etc. of the frontend library, stored right inside the source files: lib/web/css/docs/source/README.md

Trouble Shooting

Changing Files

In some cases (e.g. adding new files) it might be necessary to initialize everything again:

General “unidentified” problems

The following checklist should reset the system and make changes visible:

  1. Delete the static files relevant for the theme in:
  2. Delete the Magento caches (Backend, bin/magento CLI or n98-magerun2)
  3. bin/magento setup:static-content:deploy <lang_LANG>
  4. Start Grunt workflow


I would like to thank Maria Kern for her friendly adjustment of some missent thoughts.

Sandro Wagner

Autor: Sandro Wagner

As a trained media designer with a strong focus on frontend development and CMS integration, Sandro Wagner has worked for different leading web agencies and clients, both national and international.
At integer_net, he develops frontend designs for Magento stores, holding the corresponding Magento certificate.