I normally change the file /dev/tools/grunt/configs/themes.js but in the .gitignore we can see a configuration file called /dev/tools/grunt/configs/local-themes.js I'd like to use that file instand a core file.

I try to find something related in the DevDocs, but there's nothing about this new file.

How can I configure my theme using the file /dev/tools/grunt/configs/local-themes.js?

I don't want to create a new Grunt file or to change the core, like this questions below!

Magento 2 add new theme without changing core files. Grunt

5 Answers 5


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

npm install -g grunt-cli

followed by the initialization of the project specific dependencies

cd && npm install

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

$ grunt
Running "default" task

I'm the default task and at the moment I'm empty, sorry :/

Done, without errors.

Execution Time (2016-02-01 08:54:44 UTC)
loading tasks  393ms  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 98%
default          5ms  ▇▇ 1%
Total 400ms

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:

/', DIR );

//theme.xml --> Vendor: Theme Name Magento/luma

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

// app/design/frontend///web/css/source/_theme.less @navigation__background: @color-blue1; @navigation-desktop-level0-item__color: @color-white;

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:

// dev/tools/grunt/configs/themes.js // Add following to config array: : { area: 'frontend', name: 'Vendor/Theme', locale: 'de_DE', files: [ 'css/styles-m', 'css/styles-l' ], dsl: 'less' }

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

Clean static files and caches:

grunt clean

Collect resources and generate static files for our theme:

grunt exec:

Initialize the preprocessing:

grunt less:

Afterward, 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:

grunt watch

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).

Trouble Shooting

Changing Files

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

grunt clean

grunt exec:

grunt less:

General “unidentified” problems

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

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

You can copy file /dev/tools/grunt/configs/themes.js to /dev/tools/grunt/configs/local-themes.js

Then edit Gruntfile.js file in your magento root folder :

At line 19, change dev/tools/grunt/configs/themes to dev/tools/grunt/configs/local-themes

Hope that helps.


You can use below code to configure you custom theme for grunt in theme.js file:

blue: {
        area: 'frontend',
        name: 'Colors/blue',
        locale: 'en_US',
        files: [
        dsl: 'less'

Above cofiguration as per my theme path : app\design\frontend\Colors\blue, You have to change as per your vendor(Colors) and theme name(blue),

And run command:

grunt exec:blue  
grunt less:blue
grunt watch
  • Where do I need to create the theme.js? Aug 2, 2017 at 1:54
  • You do not have to create theme.js file, you can find this file at <root>\dev\tools\grunt\configs. Aug 2, 2017 at 5:01
  • So, I described that I don't want to change a core file. Aug 2, 2017 at 19:19
  • Thank you! @DipeshRangani . I return to this answer every time if I have a problem configuring grunt. Mar 4, 2020 at 13:30
  • When trying the above, I get the following error. Been stuck on this for a while now ... Verifying property exec.theme_name exists in config...ERROR >> Unable to process task. Warning: Required config property "exec.theme_name" missing. Use --force to continue. May 6, 2020 at 9:27

/dev/tools/grunt/configs/local-themes.js is currently at the .gitignore list and should be removed from there since it is taking the parameters as @Céline Garel described. So, this answer is also right, since Magento 2 is also planning to remove local-themes.js from the .gitignore list https://github.com/magento/magento2/pull/19350


You can copy file /dev/tools/grunt/configs/themes.js to /dev/tools/grunt/configs/local-themes.js

Then edit Gruntfile.js file in your magento root folder :

At line 19, change dev/tools/grunt/configs/themes to dev/tools/grunt/configs/local-themes

already follow your step dude @Garel but still error like this

Loading "Gruntfile.js" tasks...ERROR

SyntaxError: Unexpected token { Warning: Task "default" not found. Use --force to continue.

Aborted due to warnings.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.