Grunt commands in Magento

At this point, Grunt can be executed. We can do this by running grunt from the command line. If you are running docker-magento, be sure to prefix the command with a bin/.

When you run this command, it executes the function exported from the Gruntfile, which isn’t particularly useful at the moment.

Let’s go back to the dev/tools/grunt/configs folder, and we’ll see some other files in here such as clean, exec, and so on. Each of these files exports a function that is executed when the related name is passed to grunt.

Here is a list of common Grunt actions that are used in Magento frontend development, and when to use each:

grunt clean and exec

Let’s start by running grunt clean. Notice the pub/static and var/view_preprocessed directories are empty.

Now run grunt exec. This takes a lot longer to execute, as it runs through all of the themes in your Magento instance and builds out directories to every single Less file, with symlinks back to their appropriate fallback layer.

Open up the contents of pub/static/deployed_version.txt. This is the deployed version of the current static assets. This is used for cache busting on production systems. If we load our site and then view the source code, check out the link tags in the head. We’ll see the related deployed version in the filename of the requested static asset.

Since web browsers long-cache static assets, the only way to “bust out” of this cache is by changing the URL of the static asset. So when we run grunt exec, it not only generates all of the symlinks to static assets for our project, but it also changes the deployed version to a subsequent number. This number is just the standard unix timestamp, which will predictably update.

Looking back in the head, let’s grab this first stylesheet, which is a URL that points to the asset calendar.css. Remember, this versionNUM is just a way to bust out cached assets, so let’s look at the part of the URL after it starting with frontend.

Lets look on the filesystem for this file. If you are using my Docker setup, drop into the container with bin/bash. Now, let’s use the ls -lah command on that location at pub/static/frontend/Macademy/juno/en_US/mage/calendar.css. You’ll notice that this is a symlink to lib/web/mage/calendar.css, which is a core file.

Now, let’s run grunt clean again, which will wipe this file out. And afterwards, run grunt exec. This will take a few moments to execute, but after it does, let’s try to look for that calendar.css file again, and notice it’s not there. This is because the file is generated when the page is requested at runtime.

Let’s go back to our site, go to the Network tab, and make sure Disable cache is checked. This is important for a lot of frontend updates to make sure Chrome isn’t long-caching files, which would make our development process a pain. Go back to the Elements tab, then reload the page. It’ll take a few moments, but it will eventually reload.

At the time the page was loaded, it requested the calendar.css file, among many others, and since that file did not yet exist, Magento’s Less PHP processor created the symlink for us. And we can verify this by going back to the command line and re-running that command, and verify that the calendar.css file now exists.

The good news is that you usually only need to run grunt exec once during theme development. You only need to run it again if:

grunt less

When updates are made to Less files, the related CSS files need to be recompiled for the updates to take effect. We can do this with the grunt less command. So, any time you customize a Less file, running grunt less will compile it back down to CSS so the browser can understand it. Afterwards, you can refresh the web browser to see the updates.

This is a bit of a pain though, which is when the final grunt command comes into play…

grunt watch

Grunt watch is a helper script that listens for filesystem changes to Less files, and automatically recompiles them down to CSS. That means you don’t need to run grunt less with every update, as grunt watch does this process for you automatically.

There’s one other tool that you can use with grunt watch, and it’s called LiveReload, and it’s sort of magical. We’ll learn about it in the next lesson.

Complete and Continue